bmad-method-test-architecture-enterprise 2.0.4-next.3 → 2.0.4-next.4

package/.claude-plugin/marketplace.json

@@ -31,7 +31,7 @@
       "name": "bmad-method-test-architecture-enterprise",
       "source": "./",
       "description": "Master Test Architect module for quality strategy, test generation in red and expand modes with automatic run-and-heal, combined framework and CI setup, CI/CD quality gates, and structured testing education. The CI and ATDD commands remain available with existing customizations. Part of the BMad Method ecosystem.",
-      "version": "2.0.4-next.3",
+      "version": "2.0.4-next.4",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },

package/README.md

@@ -113,6 +113,7 @@ It requires Node.js 22.20.0 or later:
 npm install --save-dev bmad-method-test-architecture-enterprise
 ```
 
+- [`tea-teach`](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/tea-teach-cli/) teaches one learner turn and keeps conversation and session progress.
 - [`tea-test-review`](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/tea-test-review-cli/) runs the review skill against changed tests and returns a gate verdict.
 - [`tea-framework`](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/tea-framework-cli/) creates, resumes, validates, and edits test framework and CI setup with retained run evidence.
 - [`tea-trace`](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/tea-trace-cli/) maps requirements to existing evidence and returns a coverage gate.

package/cli/lib/resolve-tea-config.js

@@ -78,18 +78,22 @@ function configError(message) {
 }
 
 /** Read configuration from one pinned base commit, or from the working tree. */
-function configSource(projectRoot, baseRef) {
+function configSource(projectRoot, baseRef, inputPaths, inputPatterns) {
   if (baseRef === undefined || baseRef === null) {
     return {
+      recordInput: (file) => inputPaths?.add(file),
       label: (relativePath) => path.join(projectRoot, relativePath),
       list(pattern) {
         try {
-          return globSync(pattern, { cwd: projectRoot, dot: true, nodir: true, follow: false });
+          const matches = globSync(pattern, { cwd: projectRoot, dot: true, nodir: true, follow: false });
+          inputPatterns?.set(pattern, [...matches].sort());
+          return matches;
         } catch (error) {
           throw configError(`Failed to list policy files in ${projectRoot}: ${error.message}`);
         }
       },
       read(relativePath) {
+        inputPaths?.add(path.join(projectRoot, relativePath));
         try {
           return fs.readFileSync(path.join(projectRoot, relativePath), 'utf8');
         } catch (error) {
@@ -284,6 +288,7 @@ function parseToml(content, label) {
 function readWorkflowCustomization(source, skillRoot, projectRoot, skillName = 'bmad-testarch-test-review') {
   if (!skillRoot) return {};
   const defaultsPath = path.join(skillRoot, 'customize.toml');
+  source.recordInput?.(defaultsPath);
   let merged = {};
   try {
     merged = parseToml(fs.readFileSync(defaultsPath, 'utf8'), defaultsPath);
@@ -490,13 +495,16 @@ const KEY_TO_INSTALLED_FIELD = {
  * @param {string} [options.skillRoot] - Trusted skill defaults for workflow customization.
  * @param {object} [options.flags] - Parsed CLI options; only the keys in
  *   FLAG_TO_KEY are read, and only when not undefined.
+ * @param {Set<string>} [options.inputPaths] - Receives working-tree inputs, including missing optional layers.
+ * @param {Map<string, string[]>} [options.inputPatterns] - Receives policy glob membership used during resolution.
  * @returns {{values: object, sources: object, installed: object, configSnapshot: object, workflowCustomization: object, configCommit: string|null, configPath: string, configPresent: boolean, configFormat: string|null}}
  *   `installed` carries one boolean per library gate, read from the project
  *   manifest rather than left to the agent.
  * @throws {Error} With code TEA_CONFIG_INVALID on unusable config content.
  */
-function resolveTeaConfig({ projectRoot, flags = {}, baseRef, skillRoot, skillName }) {
-  const source = configSource(projectRoot, baseRef);
+function resolveTeaConfig({ projectRoot, flags = {}, baseRef, skillRoot, skillName, inputPaths, inputPatterns }) {
+  const source = configSource(projectRoot, baseRef, inputPaths, inputPatterns);
+  inputPaths?.add(path.join(projectRoot, 'package.json'));
   const file = readTeaConfigFile(projectRoot, baseRef, source);
   const workflowCustomization = readWorkflowCustomization(source, skillRoot, projectRoot, skillName);
 

package/cli/lib/teach-turn.js

@@ -0,0 +1,558 @@
+/** Durable learner state and evidence checks for one teaching turn. */
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const yaml = require('js-yaml');
+function isDeepStrictEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(b, key) || !isDeepStrictEqual(a[key], b[key])) return false;
+  }
+  return true;
+}
+const { projectPath, WorkflowError } = require('./workflow-cli');
+const SESSION_IDS = [
+  'session-01-quickstart',
+  'session-02-concepts',
+  'session-03-architecture',
+  'session-04-test-design',
+  'session-05-atdd-automate',
+  'session-06-quality-trace',
+  'session-07-advanced',
+];
+const FACTS = ['role', 'experience_level', 'learning_goals', 'pain_points'];
+const hash = (value) => crypto.createHash('sha256').update(value).digest('hex');
+const fail = (message) => {
+  throw new WorkflowError('environment-parser', message);
+};
+const table = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date);
+function parseProgress(text, { legacy = false } = {}) {
+  const documents = [];
+  yaml.loadAll(text, (value) => documents.push(value), { schema: yaml.JSON_SCHEMA });
+  if (documents.length !== 1 && !(legacy && documents.length === 2 && documents[1] === null))
+    fail('progress must contain one YAML document');
+  if (!table(documents[0])) fail('progress must be a YAML table');
+  return { progress: documents[0], legacyNormalized: documents.length === 2 };
+}
+function checkProgress(progress, learner) {
+  if (progress.user !== learner) fail('progress belongs to another learner');
+  if (
+    !Array.isArray(progress.sessions) ||
+    progress.sessions.length !== SESSION_IDS.length ||
+    progress.sessions.some((session, index) => !table(session) || session.id !== SESSION_IDS[index])
+  )
+    fail('progress must retain all seven canonical sessions in order');
+  for (const session of progress.sessions) {
+    if (!['not-started', 'in-progress', 'completed'].includes(session.status)) fail(`invalid status for ${session.id}`);
+    if (
+      session.score !== null &&
+      (typeof session.score !== 'number' || !Number.isFinite(session.score) || session.score < 0 || session.score > 100)
+    )
+      fail(`invalid score for ${session.id}`);
+    if (
+      session.status === 'completed' &&
+      (session.score === null ||
+        typeof session.completed_date !== 'string' ||
+        !session.completed_date.trim() ||
+        typeof session.notes_artifact !== 'string' ||
+        !session.notes_artifact.trim())
+    )
+      fail(`completed session lacks score, date or notes: ${session.id}`);
+  }
+  const completed = progress.sessions.filter((session) => session.status === 'completed').length;
+  if (
+    progress.sessions_completed !== completed ||
+    progress.total_sessions !== 7 ||
+    typeof progress.completion_percentage !== 'number' ||
+    Math.abs(progress.completion_percentage - (completed / 7) * 100) > 0.51
+  )
+    fail('progress completion counters contradict its sessions');
+  if (
+    !(
+      SESSION_IDS.includes(progress.next_recommended) ||
+      (completed === 7 && [null, 'completion', 'completed', 'none'].includes(progress.next_recommended))
+    )
+  )
+    fail('progress has an invalid next recommendation');
+  if (completed < 7 && progress.sessions.find((session) => session.id === progress.next_recommended)?.status === 'completed')
+    fail('next recommendation names an already completed session');
+  if (progress.role !== null && (typeof progress.role !== 'string' || !['qa', 'dev', 'lead', 'vp'].includes(progress.role.toLowerCase())))
+    fail('progress has an invalid role');
+  if (
+    progress.experience_level !== null &&
+    (typeof progress.experience_level !== 'string' ||
+      !['beginner', 'intermediate', 'experienced'].includes(progress.experience_level.toLowerCase()))
+  )
+    fail('progress has an invalid experience level');
+  for (const field of ['learning_goals', 'pain_points'])
+    if (progress[field] !== null && (typeof progress[field] !== 'string' || !progress[field].trim())) fail(`progress has invalid ${field}`);
+  if (
+    !Array.isArray(progress.stepsCompleted) ||
+    progress.stepsCompleted.some((step) => typeof step !== 'string') ||
+    typeof progress.lastStep !== 'string'
+  )
+    fail('progress has invalid continuation tracking');
+  if (typeof progress.summary_generated !== 'boolean') fail('progress has an invalid summary flag');
+  if (
+    progress.summary_generated &&
+    (completed !== 7 ||
+      typeof progress.summary_path !== 'string' ||
+      !progress.summary_path.trim() ||
+      typeof progress.completion_date !== 'string' ||
+      !progress.completion_date.trim())
+  )
+    fail('completed summary lacks its path, completion date or all seven sessions');
+}
+/** Every read is a fresh, singly linked regular file inside the attempt. */
+function regularArtifact(root, value) {
+  const lexical = path.resolve(root, value);
+  let resolved;
+  try {
+    resolved = projectPath(root, value, 'generated artifact');
+  } catch (error) {
+    fail(`generated artifact is outside the attempt: ${error.message}`);
+  }
+  if (resolved !== lexical) fail('generated artifact traverses a symbolic link');
+  let stat;
+  try {
+    stat = fs.lstatSync(resolved);
+  } catch {
+    fail(`generated artifact is missing: ${value}`);
+  }
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) fail(`generated artifact must be a separate regular file: ${value}`);
+  return { path: resolved, bytes: fs.readFileSync(resolved) };
+}
+/** Snapshot the entire CLI-owned directory. Symbolic and inode aliases are rejected. */
+function snapshot(root) {
+  const files = new Map();
+  if (!fs.existsSync(root)) return files;
+  const walk = (directory) => {
+    if (!fs.lstatSync(directory).isDirectory() || fs.lstatSync(directory).isSymbolicLink())
+      throw new WorkflowError('usage', 'learner state must be a regular directory');
+    for (const entry of fs.readdirSync(directory)) {
+      const file = path.join(directory, entry),
+        stat = fs.lstatSync(file);
+      if (stat.isDirectory() && !stat.isSymbolicLink()) walk(file);
+      else if (stat.isFile() && stat.nlink === 1) files.set(path.relative(root, file), fs.readFileSync(file));
+      else throw new WorkflowError('usage', 'learner state contains a symbolic link or inode alias');
+    }
+  };
+  walk(root);
+  return files;
+}
+function sameSnapshot(left, right) {
+  return left.size === right.size && [...left].every(([file, bytes]) => right.get(file)?.equals(bytes));
+}
+/** Install the directory as a unit; retain recoverable backups if rollback fails. */
+function publishState(root, files, io = fs) {
+  const parent = path.dirname(root);
+  io.mkdirSync(parent, { recursive: true });
+  const stage = io.mkdtempSync(path.join(parent, `.tea-teach-publish-${hash(root).slice(0, 16)}-`));
+  const next = path.join(stage, 'next'),
+    previous = path.join(stage, 'previous');
+  io.mkdirSync(next);
+  let moved = false,
+    installed = false,
+    keep = false;
+  try {
+    for (const [file, bytes] of files) {
+      const destination = path.join(next, file);
+      io.mkdirSync(path.dirname(destination), { recursive: true });
+      io.writeFileSync(destination, bytes, { flag: 'wx' });
+    }
+    if (io.existsSync(root)) {
+      io.renameSync(root, previous);
+      moved = true;
+    }
+    io.renameSync(next, root);
+    installed = true;
+  } catch (error) {
+    if (moved && !installed) {
+      try {
+        io.renameSync(previous, root);
+      } catch (error_) {
+        keep = true;
+        throw new WorkflowError(
+          'environment-configuration',
+          `state publication failed: ${error.message}; recovery backup: ${previous}; rollback: ${error_.message}`,
+        );
+      }
+    }
+    throw new WorkflowError('environment-configuration', `state publication failed: ${error.message}; previous state preserved`);
+  } finally {
+    if (!keep) io.rmSync(stage, { recursive: true, force: true });
+  }
+}
+/** Restore a prior learner directory if publication stopped between its two renames. */
+function recoverPublishedState(root) {
+  if (fs.existsSync(root)) return;
+  const parent = path.dirname(root);
+  const prefix = `.tea-teach-publish-${hash(root).slice(0, 16)}-`;
+  const stages = fs
+    .readdirSync(parent)
+    .filter((name) => name.startsWith(prefix))
+    .map((name) => path.join(parent, name));
+  for (const stage of stages) {
+    const stat = fs.lstatSync(stage);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+      throw new WorkflowError('usage', `interrupted learner publication has an invalid stage: ${stage}`);
+  }
+  if (stages.length === 0) return;
+  if (stages.length !== 1)
+    throw new WorkflowError('usage', `multiple interrupted learner publications need manual recovery: ${stages.join(', ')}`);
+  const previous = path.join(stages[0], 'previous');
+  if (!fs.existsSync(previous) || !fs.lstatSync(previous).isDirectory() || fs.lstatSync(previous).isSymbolicLink())
+    throw new WorkflowError('usage', `interrupted learner publication has no retained state: ${stages[0]}`);
+  fs.renameSync(previous, root);
+  fs.rmSync(stages[0], { recursive: true, force: true });
+}
+function checkConversation(value, learner, bank) {
+  if (!table(value) || value.schema_version !== '0.1.0' || value.learner !== learner || !Array.isArray(value.turns) || !table(value.quiz))
+    fail('conversation has invalid learner identity or schema');
+  if (value.activeQuiz !== undefined && !table(value.activeQuiz)) fail('conversation contains an invalid active quiz ledger');
+  const ids = new Set();
+  for (const turn of value.turns) {
+    if (
+      !table(turn) ||
+      typeof turn.id !== 'string' ||
+      ids.has(turn.id) ||
+      typeof turn.learnerMessage !== 'string' ||
+      !turn.learnerMessage.trim() ||
+      typeof turn.tutorReply !== 'string' ||
+      !turn.tutorReply.trim() ||
+      !table(turn.waiting)
+    )
+      fail('conversation contains an invalid or repeated turn');
+    ids.add(turn.id);
+  }
+  for (const [sessionId, round] of Object.entries(value.quiz)) checkQuizRound(value, bank, sessionId, round);
+  for (const [sessionId, round] of Object.entries(value.activeQuiz ?? {})) {
+    if (value.quiz[sessionId] && value.activeQuiz?.[sessionId] && value.quiz[sessionId].id === value.activeQuiz[sessionId].id)
+      fail('recorded and active quiz rounds must differ');
+    checkQuizRound(value, bank, sessionId, round);
+  }
+}
+/** Bind one recorded quiz round to its exact preceding caller questions and answers. */
+function checkQuizRound(value, bank, sessionId, round) {
+  if (!SESSION_IDS.includes(sessionId) || !table(round) || typeof round.id !== 'string' || !Array.isArray(round.answers))
+    fail('conversation contains an invalid quiz ledger');
+  for (const [index, answer] of round.answers.entries()) {
+    const turnIndex = value.turns.findIndex((item) => item.id === answer.messageId);
+    const turn = value.turns[turnIndex];
+    const pending = value.turns[turnIndex - 1]?.waiting;
+    const question = bank[sessionId]?.questions[index];
+    if (
+      !turn ||
+      turn.learnerMessage.trim().toUpperCase() !== answer.answer ||
+      !/^[ABCD]$/.test(answer.answer) ||
+      !question ||
+      answer.questionId !== question.id ||
+      answer.correct !== (answer.answer === question.correct) ||
+      pending?.kind !== 'quiz' ||
+      pending.sessionId !== sessionId ||
+      pending.questionId !== question.id ||
+      pending.roundId !== round.id
+    )
+      fail('quiz answer lacks its actual learner message');
+  }
+}
+function quizForTurn(conversation, incoming, bank) {
+  const quiz = structuredClone(conversation.quiz);
+  const activeQuiz = structuredClone(conversation.activeQuiz ?? {});
+  const pending = conversation.turns.at(-1)?.waiting;
+  if (pending?.kind === 'quiz') {
+    const item = bank[pending.sessionId]?.questions.find((question) => question.id === pending.questionId);
+    if (!item) fail('saved pending quiz question is unknown');
+    const answer = incoming.learnerMessage.trim().toUpperCase();
+    if (/^[ABCD]$/.test(answer)) {
+      const round = activeQuiz[pending.sessionId]?.id === pending.roundId ? activeQuiz[pending.sessionId] : quiz[pending.sessionId];
+      if (!round || round.id !== pending.roundId || round.answers.some((entry) => entry.questionId === item.id))
+        fail('saved quiz round is inconsistent');
+      round.answers.push({ questionId: item.id, messageId: incoming.id, answer, correct: answer === item.correct });
+    }
+  }
+  return { quiz, activeQuiz };
+}
+/** Accept only a caller assertion that answers the field's assessment question. */
+function supportsLearnerFact(turns, cited, field, value) {
+  const index = turns.findIndex((turn) => turn.id === cited);
+  if (index === -1) return false;
+  const pending = turns[index - 1]?.waiting;
+  if (pending?.kind === 'assessment' && pending.field !== field) return false;
+  const message = turns[index].learnerMessage.toLowerCase();
+  const target = value.toLowerCase();
+  const at = message.indexOf(target);
+  if (at === -1) return false;
+  if (['role', 'experience_level'].includes(field) && /[a-z0-9_]/.test(message[at - 1] ?? '')) return false;
+  if (['role', 'experience_level'].includes(field) && /[a-z0-9_]/.test(message[at + target.length] ?? '')) return false;
+  const prefix = message
+    .slice(0, at)
+    .split(/[.!?;,]/)
+    .at(-1);
+  if (/\b(?:not|never|no|without|don't|dont|cannot|can't)\b(?:\W+\w+){0,4}\W*$/.test(prefix)) return false;
+  return true;
+}
+/** Match displayed choice letters and text to the canonical quiz bank. */
+function hasCanonicalOptions(reply, question) {
+  const shown = new Map();
+  for (const line of reply.replaceAll(/\*\*|`/g, '').split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:[-*]\s*)?([ABCD])\s*[).:-]\s*(.*?)\s*$/);
+    if (!match) continue;
+    if (shown.has(match[1]) || match[2] !== question.options[match[1]]) return false;
+    shown.set(match[1], match[2]);
+  }
+  return Object.keys(question.options).every((letter) => shown.has(letter));
+}
+function scoredRound(round, questions) {
+  if (
+    !round ||
+    round.answers.length !== questions.length ||
+    questions.some((question, index) => round.answers[index]?.questionId !== question.id)
+  )
+    return null;
+  const correct = round.answers.filter((answer) => answer.correct).length;
+  return { score: Math.round((correct / questions.length) * 10_000) / 100, passed: (correct / questions.length) * 100 >= 70 };
+}
+/** Bind trusted imported completions to specific session facts; publication relocates notes. */
+function trustedSessionFingerprint(session) {
+  const facts = { ...session };
+  delete facts.notes_artifact;
+  return hash(JSON.stringify(Object.fromEntries(Object.entries(facts).sort(([left], [right]) => left.localeCompare(right)))));
+}
+/** Cross-check saved progress against caller-owned history before invoking a tutor or publishing. */
+function checkHistory(progress, conversation, bank) {
+  for (const session of progress.sessions) {
+    if (session.status !== 'completed') continue;
+    const imported = conversation.importedProgress;
+    if (
+      imported?.completedSessions?.[session.id] === trustedSessionFingerprint(session) &&
+      typeof imported.path === 'string' &&
+      typeof imported.sha256 === 'string' &&
+      /^[a-f0-9]{64}$/.test(imported.sha256)
+    )
+      continue;
+    const questions = bank[session.id]?.questions;
+    if (!Array.isArray(questions)) fail('completed session has no canonical quiz bank');
+    let result;
+    if (questions.length === 0) {
+      const completed = conversation.turns.some((turn, index) => {
+        const pending = conversation.turns[index - 1]?.waiting;
+        return (
+          pending?.kind === 'completion' && pending.sessionId === session.id && /^(?:c|complete|done)$/i.test(turn.learnerMessage.trim())
+        );
+      });
+      if (!completed) fail('saved exploratory completion lacks its caller choice');
+      result = { score: 100, passed: null };
+    } else {
+      result = scoredRound(conversation.quiz[session.id], questions);
+      if (!result) fail(`saved completion lacks caller quiz evidence: ${session.id}`);
+      if (!result.passed) {
+        const lastAnswer = conversation.quiz[session.id].answers.at(-1).messageId;
+        const answerIndex = conversation.turns.findIndex((turn) => turn.id === lastAnswer);
+        if (
+          !conversation.turns.some(
+            (turn, index) =>
+              index > answerIndex &&
+              conversation.turns[index - 1]?.waiting.kind === 'review' &&
+              conversation.turns[index - 1].waiting.sessionId === session.id &&
+              /^\[?c\]?$/i.test(turn.learnerMessage.trim()),
+          )
+        )
+          fail('saved below-pass completion lacks its caller Continue choice');
+      }
+    }
+    if (
+      Math.abs(session.score - result.score) > 0.011 ||
+      session.quiz_passed !== result.passed ||
+      ['passed', 'mastered'].some((field) => session[field] !== undefined && session[field] !== result.passed)
+    )
+      fail('saved completion contradicts its caller quiz grade');
+  }
+}
+/** Verify the tutor output against host-owned incoming messages and quiz results. */
+function validateTurn({
+  request,
+  conversation,
+  before,
+  bank,
+  attemptDir,
+  stagedRoot,
+  progressFile,
+  responseFile,
+  inputDigests,
+  assertInputsUnchanged,
+}) {
+  assertInputsUnchanged();
+  for (const [file, digest] of inputDigests) if (hash(fs.readFileSync(file)) !== digest) fail('the agent changed a supplied input');
+  const progressArtifact = regularArtifact(attemptDir, progressFile);
+  const progress = parseProgress(progressArtifact.bytes.toString('utf8')).progress;
+  checkProgress(progress, request.learner);
+  const response = JSON.parse(regularArtifact(attemptDir, responseFile).bytes);
+  if (
+    !table(response) ||
+    response.requestId !== request.requestId ||
+    response.learner !== request.learner ||
+    typeof response.reply !== 'string' ||
+    !response.reply.trim() ||
+    !table(response.waiting) ||
+    !table(response.factEvidence)
+  )
+    fail('response does not identify this learner turn');
+  if (Object.keys(response).some((key) => !['requestId', 'learner', 'reply', 'waiting', 'factEvidence'].includes(key)))
+    fail('response includes unsupported fields; learner messages are host-owned');
+  const incoming = { id: request.requestId, learnerMessage: request.message, tutorReply: response.reply, waiting: response.waiting };
+  const { quiz, activeQuiz } = quizForTurn(conversation, incoming, bank);
+  const messages = [...conversation.turns, incoming];
+  for (const field of FACTS) {
+    if (before?.[field] !== null && before?.[field] !== undefined && !isDeepStrictEqual(before[field], progress[field]))
+      fail(`the tutor changed established learner ${field}`);
+    if (
+      progress[field] !== null &&
+      (before?.[field] === null || before?.[field] === undefined) &&
+      !supportsLearnerFact(messages, response.factEvidence[field], field, progress[field])
+    )
+      fail(`learner ${field} lacks caller-message evidence`);
+  }
+  const artifacts = new Map();
+  const collect = (file) => {
+    const artifact = regularArtifact(stagedRoot, file);
+    artifacts.set(path.relative(stagedRoot, artifact.path), artifact.bytes);
+    return artifact;
+  };
+  for (const [index, session] of progress.sessions.entries()) {
+    const previous = before?.sessions[index];
+    if (session.score === null && ['quiz_passed', 'passed', 'mastered'].some((field) => session[field] === true))
+      fail('session claims mastery without quiz evidence');
+    if (previous?.status === 'completed' && !isDeepStrictEqual(previous, session))
+      fail(`the tutor changed completed session ${session.id}`);
+    if (session.status === 'completed') {
+      const notes = collect(session.notes_artifact);
+      const notesText = notes.bytes.toString('utf8');
+      const metadata = notesText.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+      if (!metadata || !notesText.slice(metadata[0].length).trim()) fail('completed session notes lack metadata or content');
+      const noteState = yaml.load(metadata[1], { schema: yaml.JSON_SCHEMA });
+      if (
+        noteState?.session_id !== session.id ||
+        noteState.user !== request.learner ||
+        Math.abs(noteState.score - session.score) > 0.011 ||
+        typeof noteState.score !== 'number'
+      )
+        fail('session notes disagree with learner, session or score');
+      if (previous?.status !== 'completed') {
+        const questions = bank[session.id]?.questions;
+        if (!Array.isArray(questions)) fail('skill quiz bank is missing this session');
+        let result;
+        if (questions.length === 0) {
+          const pending = conversation.turns.at(-1)?.waiting;
+          if (
+            pending?.kind !== 'completion' ||
+            pending.sessionId !== session.id ||
+            previous?.status !== 'in-progress' ||
+            !/^(?:c|complete|done)$/i.test(request.message.trim())
+          )
+            fail('exploratory completion requires the learner’s explicit completion choice');
+          result = { score: 100, passed: null };
+        } else {
+          result = scoredRound(activeQuiz[session.id] ?? quiz[session.id], questions);
+          if (!result) fail('session completion lacks all three caller-owned quiz answers');
+          const pending = conversation.turns.at(-1)?.waiting;
+          if (
+            !result.passed &&
+            !(pending?.kind === 'review' && pending.sessionId === session.id && /^\[?c\]?$/i.test(request.message.trim()))
+          )
+            fail('below-pass completion requires the learner’s explicit Continue choice');
+        }
+        if (Math.abs(session.score - result.score) > 0.011) fail('session score disagrees with its actual quiz evidence');
+        for (const field of ['quiz_passed', 'passed', 'mastered'])
+          if (session[field] !== undefined && session[field] !== result.passed) fail('session claims unearned mastery');
+        session.quiz_passed = result.passed;
+        if (activeQuiz[session.id]) {
+          quiz[session.id] = activeQuiz[session.id];
+          delete activeQuiz[session.id];
+        }
+      }
+    } else if (session.score !== null) {
+      const activeResult = scoredRound(activeQuiz[session.id], bank[session.id]?.questions ?? []);
+      const result = activeResult ?? scoredRound(quiz[session.id], bank[session.id]?.questions ?? []);
+      if (!result || Math.abs(session.score - result.score) > 0.011) fail('session score lacks complete quiz evidence');
+      for (const field of ['quiz_passed', 'passed', 'mastered'])
+        if (session[field] !== undefined && session[field] !== result.passed) fail('session claims unearned mastery');
+      if (activeResult) {
+        quiz[session.id] = activeQuiz[session.id];
+        delete activeQuiz[session.id];
+      }
+    }
+  }
+  const waiting = response.waiting;
+  if (
+    ['lesson', 'quiz', 'review', 'completion'].includes(waiting.kind) &&
+    ['role', 'experience_level', 'learning_goals'].some((field) => progress[field] === null)
+  )
+    fail('teaching requires the caller-supported learner assessment');
+  if (!['assessment', 'menu', 'lesson', 'quiz', 'review', 'completion'].includes(waiting.kind))
+    fail('response has an invalid learner stop point');
+  if (['lesson', 'quiz', 'review', 'completion'].includes(waiting.kind) && !SESSION_IDS.includes(waiting.sessionId))
+    fail('response stop point has no canonical session');
+  if (waiting.kind === 'assessment' && !FACTS.includes(waiting.field)) fail('assessment stop point has no known field');
+  if (waiting.kind === 'quiz') {
+    const questions = bank[waiting.sessionId].questions;
+    const question = questions.find((item) => item.id === waiting.questionId);
+    if (!question || !response.reply.includes(question.question) || !hasCanonicalOptions(response.reply, question))
+      fail('pending quiz reply omits its canonical question or options');
+    let round = activeQuiz[waiting.sessionId] ?? quiz[waiting.sessionId];
+    if (
+      waiting.questionId === questions[0].id &&
+      (conversation.turns.at(-1)?.waiting.kind !== 'quiz' || round?.answers.length === questions.length)
+    )
+      round = (scoredRound(quiz[waiting.sessionId], questions) ? activeQuiz : quiz)[waiting.sessionId] = {
+        id: crypto.randomUUID(),
+        answers: [],
+      };
+    if (!round || questions[round.answers.length]?.id !== waiting.questionId) fail('pending quiz skips unanswered questions');
+    waiting.roundId = round.id;
+  }
+  if (
+    waiting.kind === 'review' &&
+    !scoredRound(activeQuiz[waiting.sessionId] ?? quiz[waiting.sessionId], bank[waiting.sessionId].questions)
+  )
+    fail('review stop point lacks a completed quiz');
+  if (progress.summary_generated) {
+    if (progress.sessions_completed !== 7 || typeof progress.summary_path !== 'string')
+      fail('completion summary lacks all seven completed sessions');
+    collect(progress.summary_path);
+  }
+  if (before?.summary_generated && (!progress.summary_generated || progress.summary_path !== before.summary_path))
+    fail('the tutor changed the established completion summary');
+  if (before?.completion_date != null && progress.completion_date !== before.completion_date)
+    fail('the tutor changed the established completion date');
+  if (before && before.stepsCompleted.some((step) => !progress.stepsCompleted.includes(step)))
+    fail('the tutor discarded saved workflow steps');
+  const nextConversation = { ...conversation, turns: messages, quiz, activeQuiz };
+  checkConversation(nextConversation, request.learner, bank);
+  checkHistory(progress, nextConversation, bank);
+  return { progress, conversation: nextConversation, artifacts };
+}
+module.exports = {
+  SESSION_IDS,
+  FACTS,
+  hash,
+  parseProgress,
+  checkProgress,
+  regularArtifact,
+  snapshot,
+  sameSnapshot,
+  publishState,
+  recoverPublishedState,
+  checkConversation,
+  trustedSessionFingerprint,
+  checkHistory,
+  quizForTurn,
+  scoredRound,
+  validateTurn,
+};

package/cli/teach.js

@@ -0,0 +1,433 @@
+#!/usr/bin/env node
+/** Run one explicit learner message through the packaged teaching skill. */
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const yaml = require('js-yaml');
+const { globSync } = require('glob');
+const { Command } = require('commander');
+const { resolveTeaConfig } = require('./lib/resolve-tea-config');
+const { protectSources } = require('./lib/workflow-publication');
+const {
+  addAgentOptions,
+  agentOptions,
+  readInput,
+  projectPath,
+  resolveWorkflowSkill,
+  runWithEvidence,
+  WorkflowError,
+  mainError,
+} = require('./lib/workflow-cli');
+const {
+  hash,
+  parseProgress,
+  checkProgress,
+  snapshot,
+  sameSnapshot,
+  publishState,
+  recoverPublishedState,
+  checkConversation,
+  checkHistory,
+  trustedSessionFingerprint,
+  validateTurn,
+} = require('./lib/teach-turn');
+const NAME = 'tea-teach';
+const serialize = (value) => Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+function within(root, file) {
+  const relative = path.relative(root, file);
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+function aliases(left, right) {
+  if (left === right) return true;
+  if (!fs.existsSync(left) || !fs.existsSync(right)) return false;
+  const a = fs.statSync(left),
+    b = fs.statSync(right);
+  return a.dev === b.dev && a.ino === b.ino;
+}
+function promptFor(request, config, conversation, bank) {
+  return [
+    `Run the actual TEA teaching skill at ${JSON.stringify(request.skillRoot)}. Read its SKILL.md completely and follow its teaching steps in order.`,
+    `Project root: ${JSON.stringify(request.projectRoot)}. Knowledge root: ${JSON.stringify(path.resolve(request.skillRoot, '..', 'bmod-tea', 'knowledge'))}.`,
+    'This is one learner turn in create/continue mode. The explicit learner name overrides config.user_name. Read only the supplied history and incoming learner message as learner responses.',
+    'Ask the next teaching question or show the next menu in the reply artifact, then stop. Questions to the learner belong in that reply. Do not ask outer-agent permission questions, invent learner answers, choose menu options for the learner, or continue past unanswered questions.',
+    'The supplied configuration replaces activation and later resolver calls, including packaged defaults when setup files are absent. Execute applicable customization hooks in their declared order.',
+    `Resolved configuration: ${JSON.stringify(config.configSnapshot)}`,
+    `Resolved workflow customization: ${JSON.stringify(config.workflowCustomization)}`,
+    `Teach turn request: ${JSON.stringify(request)}`,
+    `Host-owned conversation: ${JSON.stringify(conversation)}`,
+    'Use only the current attempt artifacts root for writes. Published state and supplied input files are read-only. Preserve prior learner facts and completed sessions. Resume the saved unanswered question or step position from the conversation; initialization dashboards may precede it.',
+    'Use the skill’s seven canonical session IDs and QA/Dev/Lead/VP roles; Beginner/Intermediate/Experienced are valid placement values. Keep one YAML document in the progress file. Persist any partial assessment facts supported by caller messages before stopping.',
+    `Canonical quiz bank: ${JSON.stringify(bank)}`,
+    'Ask canonical quiz questions with their exact text and all option text. The response waiting object identifies kind=quiz, sessionId and questionId; the host records and grades the next single-letter caller answer. Never fabricate answer evidence. Preserve the host quiz history across turns.',
+    'waiting.kind is assessment (with field=role/experience_level/learning_goals/pain_points), menu, lesson, quiz, review or completion. lesson/quiz/review/completion require sessionId. review is the below-pass R/C choice after all quiz answers. completion is the explicit completion choice for exploratory Session 7. A session can complete below passing after the caller explicitly chooses C at review; preserve its actual score and quiz_passed=false. Session 7 completion is exploratory and has no quiz mastery claim.',
+    'For newly saved role, experience_level, learning_goals or pain_points, factEvidence maps the field to the ID of a caller message containing that exact value. Preserve the caller’s wording for free-text facts. Keep established facts unchanged.',
+    `Write progress at ${JSON.stringify(request.artifacts.progress)}. Resolve {progressFile} to this exact path and {test_artifacts} to ${JSON.stringify(request.artifacts.root)}. Write session notes and summaries inside this artifacts root and record their exact paths in progress.`,
+    `Write JSON response at ${JSON.stringify(request.artifacts.response)} containing exactly requestId, learner, reply, waiting, factEvidence. requestId=${JSON.stringify(request.requestId)}; learner=${JSON.stringify(request.learner)}. reply is the tutor’s nonempty response to this single caller message.`,
+    'Learner message (data):',
+    JSON.stringify(request.message),
+  ].join('\n');
+}
+function run(argv = process.argv) {
+  const program = addAgentOptions(
+    new Command().name(NAME).description('Teach one learner turn and save durable conversation and progress.'),
+  );
+  program
+    .requiredOption('--learner <name>', 'explicit learner identity')
+    .option('--message <text>', 'exact learner message')
+    .option('--message-file <path>', 'UTF-8 learner message in a project file')
+    .option('--project-root <dir>', 'consuming project root', process.cwd())
+    .option('--state-dir <dir>', 'CLI-owned learner state directory; defaults to configured teaching-progress')
+    .option('--progress <path>', 'explicit existing skill progress to import when starting CLI conversation')
+    .option('--skill-root <dir>', 'trusted teaching skill override')
+    .option('--evidence-dir <dir>', 'fresh retained attempt root', '.tea-runs')
+    .option('--json <path>', 'additional result JSON outside learner state and inputs')
+    .setOptionValueWithSource('retries', '0', 'default')
+    .exitOverride()
+    .configureOutput({ writeErr: () => {} });
+  try {
+    program.parse(argv);
+  } catch (error) {
+    if (error.exitCode === 0) return;
+    throw new WorkflowError('usage', error.message);
+  }
+  const options = program.opts();
+  const root = fs.realpathSync(path.resolve(options.projectRoot));
+  if (!fs.statSync(root).isDirectory()) throw new WorkflowError('usage', '--project-root must be a directory');
+  agentOptions(options, root);
+  if (
+    typeof options.learner !== 'string' ||
+    !/^[\p{L}\p{N}][\p{L}\p{N} ._'()-]{0,79}$/u.test(options.learner) ||
+    options.learner.trim() !== options.learner
+  )
+    throw new WorkflowError('usage', '--learner must be a name of 1 to 80 letters, digits, spaces or safe punctuation');
+  if ((options.message === undefined) === (options.messageFile === undefined))
+    throw new WorkflowError('usage', 'supply exactly one --message or --message-file');
+  const inputFile = options.messageFile ? readInput(root, options.messageFile, '--message-file') : null;
+  const message = inputFile ? new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(inputFile)) : options.message;
+  if (!message.trim()) throw new WorkflowError('usage', 'learner message must be nonempty');
+  const skillRoot = resolveWorkflowSkill({ projectRoot: root, skillName: 'bmad-teach-me-testing', skillRoot: options.skillRoot });
+  const consumedInputs = new Set();
+  const inputPatterns = new Map();
+  const config = resolveTeaConfig({
+    projectRoot: root,
+    skillRoot,
+    skillName: 'bmad-teach-me-testing',
+    inputPaths: consumedInputs,
+    inputPatterns,
+  });
+  config.configSnapshot.core.user_name = options.learner;
+  const configuredArtifacts = config.configSnapshot.modules.tea.test_artifacts;
+  if (typeof configuredArtifacts !== 'string' || !configuredArtifacts.trim())
+    throw new WorkflowError('environment-configuration', 'modules.tea.test_artifacts must be a nonempty path string');
+  const artifactRoot = configuredArtifacts.replaceAll('{project-root}', root);
+  const slug =
+    options.learner
+      .toLowerCase()
+      .replaceAll(/[^a-z0-9]+/g, '-')
+      .replaceAll(/^-|-$/g, '') || 'learner';
+  const key = `${slug}-${hash(options.learner).slice(0, 12)}`;
+  const stateDir = projectPath(root, options.stateDir ?? path.join(artifactRoot, 'teaching-progress', key), '--state-dir');
+  const evidenceDir = projectPath(root, options.evidenceDir, '--evidence-dir');
+  if (stateDir === root || within(stateDir, evidenceDir) || within(evidenceDir, stateDir))
+    throw new WorkflowError('usage', 'learner state and evidence must be separate project directories');
+  if (inputFile && within(stateDir, inputFile)) throw new WorkflowError('usage', 'message input must be outside learner state');
+  const imported = options.progress ? readInput(root, options.progress, '--progress') : null;
+  const progressName = `${options.learner}-tea-progress.yaml`;
+  const progressPath = path.join(stateDir, progressName),
+    conversationPath = path.join(stateDir, 'conversation.json');
+  const jsonPath = options.json ? projectPath(root, options.json, '--json') : null;
+  const inputs = [
+    inputFile,
+    imported,
+    config.configPath,
+    ...consumedInputs,
+    ...[
+      '_bmad/config.toml',
+      '_bmad/config.user.toml',
+      '_bmad/custom/config.toml',
+      '_bmad/custom/config.user.toml',
+      'package.json',
+      'package-lock.json',
+      '_bmad/custom/bmad-teach-me-testing.toml',
+      '_bmad/custom/bmad-teach-me-testing.user.toml',
+    ].map((file) => path.join(root, file)),
+  ].filter(Boolean);
+  const guard = () => {
+    if (projectPath(root, stateDir, '--state-dir') !== stateDir || projectPath(root, evidenceDir, '--evidence-dir') !== evidenceDir)
+      throw new WorkflowError('usage', 'state or evidence path changed through an alias');
+    if (inputs.some((file) => within(stateDir, file) || within(evidenceDir, file)))
+      throw new WorkflowError('usage', 'state and evidence must be separate from configuration and supplied inputs');
+    if (!jsonPath) return;
+    if (
+      projectPath(root, jsonPath, '--json') !== jsonPath ||
+      within(stateDir, jsonPath) ||
+      within(evidenceDir, jsonPath) ||
+      inputs.some((file) => aliases(file, jsonPath))
+    )
+      throw new WorkflowError('usage', '--json aliases protected state, input or evidence');
+    if (path.extname(jsonPath) !== '.json' || (fs.existsSync(jsonPath) && !fs.statSync(jsonPath).isFile()))
+      throw new WorkflowError('usage', '--json must name a separate regular .json file');
+  };
+  guard();
+  fs.mkdirSync(path.dirname(stateDir), { recursive: true });
+  const lock = path.join(path.dirname(stateDir), `.tea-teach-lock-${hash(stateDir).slice(0, 16)}`);
+  try {
+    fs.mkdirSync(lock);
+  } catch (error) {
+    throw new WorkflowError(
+      'usage',
+      `learner state is locked by another invocation at ${lock}; remove this lock only after confirming that invocation has ended`,
+      { cause: error },
+    );
+  }
+  let original;
+  let originalExisted;
+  let execution;
+  try {
+    recoverPublishedState(stateDir);
+    originalExisted = fs.existsSync(stateDir);
+    original = snapshot(stateDir);
+    if (imported && original.size > 0) throw new WorkflowError('usage', '--progress import requires an empty CLI learner state');
+    if (original.has('conversation.json') && !original.has(progressName))
+      throw new WorkflowError('usage', 'saved conversation requires its paired learner progress');
+    let before = null,
+      legacyNormalized = false;
+    if (original.has(progressName) || imported) {
+      try {
+        const parsed = parseProgress(imported ? fs.readFileSync(imported, 'utf8') : original.get(progressName).toString('utf8'), {
+          legacy: Boolean(imported),
+        });
+        before = parsed.progress;
+        legacyNormalized = parsed.legacyNormalized;
+        checkProgress(before, options.learner);
+      } catch (error) {
+        throw new WorkflowError('usage', `invalid saved progress: ${error.message}`);
+      }
+    }
+    let conversation = {
+      schema_version: '0.1.0',
+      learner: options.learner,
+      turns: [],
+      quiz: {},
+      importedProgress: imported
+        ? {
+            path: imported,
+            sha256: hash(fs.readFileSync(imported)),
+            legacyNormalized,
+            trustedPriorCompletions: before.sessions_completed,
+            completedSessions: Object.fromEntries(
+              before.sessions
+                .filter((session) => session.status === 'completed')
+                .map((session) => [session.id, trustedSessionFingerprint(session)]),
+            ),
+          }
+        : null,
+    };
+    const bank = yaml.load(fs.readFileSync(path.join(skillRoot, 'data/quiz-questions.yaml'), 'utf8'), { schema: yaml.JSON_SCHEMA });
+    try {
+      if (original.has('conversation.json')) conversation = JSON.parse(original.get('conversation.json'));
+      else if (before && !imported) throw new Error('existing progress requires its saved conversation or explicit --progress import');
+      checkConversation(conversation, options.learner, bank);
+      if (before) checkHistory(before, conversation, bank);
+    } catch (error) {
+      throw new WorkflowError('usage', `invalid saved conversation: ${error.message}`);
+    }
+    const heldInputs = [...new Set(inputs)];
+    const importedArtifacts = new Map();
+    if (imported)
+      for (const file of [
+        ...before.sessions.map((session) => session.notes_artifact).filter(Boolean),
+        ...(before.summary_generated ? [before.summary_path] : []),
+      ]) {
+        const source = readInput(root, file, 'imported teaching artifact');
+        heldInputs.push(source);
+        importedArtifacts.set(source, fs.readFileSync(source));
+      }
+    inputs.push(...heldInputs);
+    guard();
+    // Skill defaults may live outside the consuming project. Freeze them under their own root.
+    const projectInputs = heldInputs.filter((file) => within(root, file));
+    const absentInputs = heldInputs.filter((file) => !fs.existsSync(file));
+    const protections = [
+      protectSources(
+        root,
+        projectInputs.filter((file) => fs.existsSync(file)),
+      ),
+      protectSources(
+        skillRoot,
+        [...consumedInputs].filter((file) => within(skillRoot, file) && fs.existsSync(file)),
+      ),
+    ];
+    const assertInputsUnchanged = () => {
+      for (const protection of protections) protection.assertUnchanged();
+      if (absentInputs.some((file) => fs.existsSync(file)))
+        throw new WorkflowError('environment-parser', 'the agent created a previously absent configuration input');
+      for (const [pattern, matches] of inputPatterns) {
+        const current = globSync(pattern, { cwd: root, dot: true, nodir: true, follow: false }).sort();
+        if (JSON.stringify(current) !== JSON.stringify(matches))
+          throw new WorkflowError('environment-parser', 'the agent changed customization policy membership');
+      }
+    };
+    assertInputsUnchanged();
+    const requestId = crypto.randomUUID();
+    execution = runWithEvidence({
+      name: NAME,
+      projectRoot: root,
+      evidenceRoot: evidenceDir,
+      options,
+      prepare({ attemptDir }) {
+        assertInputsUnchanged();
+        const stagedRoot = path.join(attemptDir, 'artifacts');
+        fs.mkdirSync(stagedRoot);
+        for (const [file, bytes] of original)
+          if (file.startsWith(`artifacts${path.sep}`)) {
+            const target = path.join(stagedRoot, path.relative('artifacts', file));
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, bytes, { flag: 'wx' });
+          }
+        const stagedBefore = before ? structuredClone(before) : null;
+        if (stagedBefore) {
+          for (const session of stagedBefore.sessions)
+            if (session.notes_artifact) {
+              if (imported) {
+                const source = readInput(root, session.notes_artifact, 'imported notes');
+                const target = path.join(stagedRoot, 'imported-notes', `${session.id}.md`);
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                fs.writeFileSync(target, importedArtifacts.get(source));
+                session.notes_artifact = target;
+              } else {
+                if (!within(path.join(stateDir, 'artifacts'), session.notes_artifact))
+                  throw new WorkflowError('usage', 'saved notes escape CLI-owned artifacts');
+                session.notes_artifact = path.join(stagedRoot, path.relative(path.join(stateDir, 'artifacts'), session.notes_artifact));
+              }
+            }
+          if (stagedBefore.summary_path) {
+            if (imported) {
+              const source = readInput(root, stagedBefore.summary_path, 'imported summary');
+              const target = path.join(stagedRoot, 'imported-summary.md');
+              fs.writeFileSync(target, importedArtifacts.get(source));
+              stagedBefore.summary_path = target;
+            } else {
+              if (!within(path.join(stateDir, 'artifacts'), stagedBefore.summary_path))
+                throw new WorkflowError('usage', 'saved summary escapes CLI-owned artifacts');
+              stagedBefore.summary_path = path.join(stagedRoot, path.relative(path.join(stateDir, 'artifacts'), stagedBefore.summary_path));
+            }
+          }
+        }
+        const progressFile = path.join(stagedRoot, 'teaching-progress', progressName),
+          responseFile = path.join(attemptDir, 'response.json');
+        fs.mkdirSync(path.dirname(progressFile), { recursive: true });
+        if (stagedBefore) fs.writeFileSync(progressFile, yaml.dump(stagedBefore));
+        const request = {
+          requestId,
+          learner: options.learner,
+          message,
+          projectRoot: root,
+          skillRoot,
+          previous: Boolean(before),
+          artifacts: { root: stagedRoot, progress: progressFile, response: responseFile },
+        };
+        const stagedConfig = structuredClone(config);
+        stagedConfig.configSnapshot.modules.tea.test_artifacts = stagedRoot;
+        return {
+          prompt: promptFor(request, stagedConfig, conversation, bank),
+          request,
+          conversation,
+          before: stagedBefore,
+          bank,
+          stagedRoot,
+          progressFile,
+          responseFile,
+          assertInputsUnchanged,
+          inputDigests: [
+            ...(stagedBefore?.sessions
+              .filter((session) => session.status === 'completed')
+              .map((session) => [session.notes_artifact, hash(fs.readFileSync(session.notes_artifact))]) ?? []),
+            ...(stagedBefore?.summary_generated ? [[stagedBefore.summary_path, hash(fs.readFileSync(stagedBefore.summary_path))]] : []),
+          ],
+        };
+      },
+      validate: validateTurn,
+    });
+    guard();
+    assertInputsUnchanged();
+    if (!sameSnapshot(original, snapshot(stateDir)))
+      throw new WorkflowError('environment-parser', 'the agent changed published learner state');
+    if (execution.dryRun) {
+      process.stdout.write(
+        `${JSON.stringify({ mode: 'prompt-only', evidence: execution.runDir, prompt: path.join(execution.attemptDir, 'prompt.txt') })}\n`,
+      );
+      return;
+    }
+    const value = execution.value;
+    const next = new Map(original);
+    for (const [file, bytes] of value.artifacts) next.set(path.join('artifacts', file), bytes);
+    for (const session of value.progress.sessions)
+      if (session.notes_artifact)
+        session.notes_artifact = path.join(stateDir, 'artifacts', path.relative(execution.context.stagedRoot, session.notes_artifact));
+    if (value.progress.summary_path)
+      value.progress.summary_path = path.join(
+        stateDir,
+        'artifacts',
+        path.relative(execution.context.stagedRoot, value.progress.summary_path),
+      );
+    next.set(progressName, Buffer.from(yaml.dump(value.progress)));
+    next.set('conversation.json', serialize(value.conversation));
+    checkHistory(value.progress, value.conversation, bank);
+    assertInputsUnchanged();
+    publishState(stateDir, next);
+    const payload = {
+      schema_version: '0.1.0',
+      mode: 'live',
+      learner: options.learner,
+      reply: value.conversation.turns.at(-1).tutorReply,
+      waiting: value.conversation.turns.at(-1).waiting,
+      progress: progressPath,
+      conversation: conversationPath,
+      sessions_completed: value.progress.sessions_completed,
+      evidence: execution.runDir,
+    };
+    guard();
+    if (jsonPath) {
+      fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
+      fs.writeFileSync(jsonPath, serialize(payload));
+    }
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } catch (error) {
+    if (original) {
+      let changed;
+      try {
+        changed = !sameSnapshot(original, snapshot(stateDir));
+      } catch {
+        changed = true;
+      }
+      if (changed && projectPath(root, path.dirname(stateDir)) === path.dirname(stateDir)) {
+        try {
+          publishState(stateDir, original);
+          if (!originalExisted) fs.rmdirSync(stateDir);
+        } catch (error_) {
+          error.message += `; state recovery failed: ${error_.message}`;
+        }
+      }
+    }
+    if (execution?.runDir && !error.runDir) error.runDir = execution.runDir;
+    // Failure payloads stay on stdout and retained stderr; never publish failed state or overwrite --json.
+    process.stdout.write(
+      `${JSON.stringify({ schema_version: '0.1.0', status: 'failed', reason: error.message, evidence: error.runDir ?? null })}\n`,
+    );
+    throw error;
+  } finally {
+    fs.rmdirSync(lock);
+  }
+}
+function main(argv = process.argv) {
+  try {
+    run(argv);
+    return 0;
+  } catch (error) {
+    return mainError(NAME, error);
+  }
+}
+if (require.main === module) process.exitCode = main();
+module.exports = { main, run, promptFor };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "2.0.4-next.3",
+  "version": "2.0.4-next.4",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",
@@ -42,6 +42,7 @@
     "tea-nfr-runner": "cli/nfr-runner.js",
     "tea-routing-runner": "cli/routing-runner.js",
     "tea-skill-runner": "cli/skill-runner.js",
+    "tea-teach": "cli/teach.js",
     "tea-test-design": "cli/test-design.js",
     "tea-test-design-runner": "cli/test-design-runner.js",
     "tea-test-review": "cli/test-review.js",
@@ -93,7 +94,7 @@
     "release:minor": "gh workflow run publish.yaml -f channel=latest -f bump=minor",
     "release:next": "gh workflow run publish.yaml -f channel=next",
     "release:patch": "gh workflow run publish.yaml -f channel=latest -f bump=patch",
-    "test": "npm run test:conflict-markers && npm run test:schemas && npm run test:install && npm run test:evaluate-guidance && npm run test:evaluate-authoring && npm run test:evaluate-gap-loop && npm run test:evaluate-dogfood && npm run test:evaluate-check && npm run test:evaluate-compare && npm run test:evaluate-before-state && npm run test:evaluate-ci-gates && npm run test:evaluate-ci-tiers && npm run test:evaluate-ci-repositories:tagged-release-pr && npm run test:evaluate-ci-repositories:tagged-release-merge && npm run test:evaluate-ci-repositories:tagged-release-release && npm run test:evaluate-ci-repositories:nightly-deploy-pr && npm run test:evaluate-ci-repositories:nightly-deploy-merge && npm run test:evaluate-ci-repositories:nightly-deploy-scheduled && npm run test:evaluate-ci-repositories:nightly-deploy-release && npm run test:evaluate-ci-render && npm run test:evaluate-pr-mcp && npm run test:evaluate-pr-api && npm run test:evaluate-pr-suite && npm run test:evaluate-pr-workflow && npm run test:evaluate-pr-tool-use && npm run test:evaluate-pr-promptfoo && npm run test:evaluate-pr-ai-feature && npm run test:evaluate-pr-test-review && npm run test:evaluate-pr-gap-loop && npm run test:evaluate-pr-learn && npm run test:evaluate-pr-tutorial && npm run test:evaluate-partitions && npm run test:evaluate-partition-plans-views-and-check && npm run test:evaluate-partition-plans-preflight-and-run && npm run test:evaluate-partition-plans-score && npm run test:evaluate-partition-plans-attempts-seal-and-mappings && npm run test:evaluate-partition-plans-attempts-records && npm run test:evaluate-partition-plans-attempts-gameability && npm run test:evaluate-interpret && npm run test:evaluate-calibration && npm run test:evaluate-boundaries && npm run test:evaluate-preflight && npm run test:evaluate-isolation-conformance && npm run test:evaluate-mutation:qualification-basics && npm run test:evaluate-mutation:qualification-guards && npm run test:evaluate-mutation:recovery && npm run test:evaluate-mutation:journals && npm run test:evaluate-run && npm run test:evaluate-progress && npm run test:evaluate-aggregate && npm run test:evaluate-confinement && npm run test:evaluate-confinement-audit && npm run test:evaluate-confinement-history && npm run test:evaluate-confinement-git-state && npm run test:evaluate-confinement-network && npm run test:evaluate-held-inputs && npm run test:evaluate-arms-historical && npm run test:evaluate-arms-deployments && npm run test:evaluate-evaluators && npm run test:evaluate-evaluators-agent-version && npm run test:evaluate-agents && npm run test:evaluate-agents-importers && npm run test:evaluate-agents-sealed-brief && npm run test:evaluate-held-attempts && npm run test:evaluate-private && npm run test:evaluate-records && npm run test:evaluate-mcp && npm run test:evaluate-api && npm run test:evaluate-workflow && npm run test:evaluate-tool-use && npm run test:evaluate-promptfoo && npm run test:evaluate-learned-framework && npm run test:docs-tutorial && npm run test:knowledge && npm run test:criteria-fragments && npm run test:doc-count-sources && npm run test:planning-doc-sources && npm run test:doc-counts && npm run test:doc-claim-sources && npm run test:doc-claims && npm run test:doc-invocation-entry && npm run test:doc-invocations && npm run test:doc-link-anchors && npm run test:docs-build-names && npm run test:docs-evaluate-sidebar && npm run test:docs-gap-reader && npm run test:enforce-hook && npm run test:framework-scaffold && npm run test:isolation-primitives && npm run test:atdd-isolation && npm run test:atdd-net-guard && npm run test:atdd-scoring && npm run test:atdd-workflow-guidance && npm run test:generation-healing && npm run test:framework-scaffold-install-isolation && npm run test:transcript-harness && npm run test:suite-manifest && npm run test:teach-me-testing-scoring && npm run test:eval-data && npm run test:eval-atdd-data && npm run test:eval-ci-data && npm run test:eval-framework-scaffold-data && npm run test:eval-nfr-data && npm run test:nfr-validate-corpus && npm run test:nfr-evidence-guidance && npm run test:nfr-cli && npm run test:eval-test-design-data && npm run test:eval-trace-data && npm run test:eval-routing-data && npm run test:eval-routing-boundaries && npm run test:eval-routing-evidence && npm run test:eval-transcript-data && npm run test:eval-teach-me-testing-data && npm run test:eval-schemas && npm run test:eval-diagnostics && npm run test:eval-replay && npm run test:eval-quality-corpus && npm run test:schema-versions && npm run test:contract-sources && npm run test:contracts && npm run test:contract-oracles && npm run test:probe-sources && npm run test:test-design-qualification && npm run test:test-review-qualification && npm run test:trace-qualification && npm run test:nfr-qualification && npm run test:ci-qualification && npm run test:probe-corpus && npm run test:compare-dominance && npm run test:compare-eval-runs && npm run test:trial-set-scoring && npm run test:automate-cli && npm run test:automate-generation-evidence && npm run test:automate-eval-fixture && npm run test:eval-automate-data && npm run test:clock-port && npm run test:probe-conformance && npm run test:corpus-conformance && npm run test:file-system-conformance && npm run test:file-system-port && npm run test:probe-targets && npm run test:port-totality && npm run test:ci-coverage && npm run test:ci-coverage-filters && npm run test:install-actionlint && npm run test:workflows-lint && npm run test:install-linux-sandbox && npm run test:shards && npm run test:groups && npm run test:cli && npm run test:workflow-cli && npm run test:framework-cli && npm run test:test-review-pr-scope && npm run test:test-review-report && npm run test:test-review-rubric && npm run test:bmad-output-gated && npm run test:release-metadata && npm run test:release-notes && npm run test:lockfile-age && npm run test:lockfile-age-cache && npm run test:licences && npm run test:supply-chain && npm run test:boundary && npm run test:direction && npm run test:lineage && npm run test:guard-publish && npm run test:layering-boundary-lineage && npm run test:changelog && npm run test:tea-workflow-descriptions && npm run test:docs-mermaid && npm run test:llms-headroom && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:conflict-markers && npm run test:schemas && npm run test:install && npm run test:evaluate-guidance && npm run test:evaluate-authoring && npm run test:evaluate-gap-loop && npm run test:evaluate-dogfood && npm run test:evaluate-check && npm run test:evaluate-compare && npm run test:evaluate-before-state && npm run test:evaluate-ci-gates && npm run test:evaluate-ci-tiers && npm run test:evaluate-ci-repositories:tagged-release-pr && npm run test:evaluate-ci-repositories:tagged-release-merge && npm run test:evaluate-ci-repositories:tagged-release-release && npm run test:evaluate-ci-repositories:nightly-deploy-pr && npm run test:evaluate-ci-repositories:nightly-deploy-merge && npm run test:evaluate-ci-repositories:nightly-deploy-scheduled && npm run test:evaluate-ci-repositories:nightly-deploy-release && npm run test:evaluate-ci-render && npm run test:evaluate-pr-mcp && npm run test:evaluate-pr-api && npm run test:evaluate-pr-suite && npm run test:evaluate-pr-workflow && npm run test:evaluate-pr-tool-use && npm run test:evaluate-pr-promptfoo && npm run test:evaluate-pr-ai-feature && npm run test:evaluate-pr-test-review && npm run test:evaluate-pr-gap-loop && npm run test:evaluate-pr-learn && npm run test:evaluate-pr-tutorial && npm run test:evaluate-partitions && npm run test:evaluate-partition-plans-views-and-check && npm run test:evaluate-partition-plans-preflight-and-run && npm run test:evaluate-partition-plans-score && npm run test:evaluate-partition-plans-attempts-seal-and-mappings && npm run test:evaluate-partition-plans-attempts-records && npm run test:evaluate-partition-plans-attempts-gameability && npm run test:evaluate-interpret && npm run test:evaluate-calibration && npm run test:evaluate-boundaries && npm run test:evaluate-preflight && npm run test:evaluate-isolation-conformance && npm run test:evaluate-mutation:qualification-basics && npm run test:evaluate-mutation:qualification-guards && npm run test:evaluate-mutation:recovery && npm run test:evaluate-mutation:journals && npm run test:evaluate-run && npm run test:evaluate-progress && npm run test:evaluate-aggregate && npm run test:evaluate-confinement && npm run test:evaluate-confinement-audit && npm run test:evaluate-confinement-history && npm run test:evaluate-confinement-git-state && npm run test:evaluate-confinement-network && npm run test:evaluate-held-inputs && npm run test:evaluate-arms-historical && npm run test:evaluate-arms-deployments && npm run test:evaluate-evaluators && npm run test:evaluate-evaluators-agent-version && npm run test:evaluate-agents && npm run test:evaluate-agents-importers && npm run test:evaluate-agents-sealed-brief && npm run test:evaluate-held-attempts && npm run test:evaluate-private && npm run test:evaluate-records && npm run test:evaluate-mcp && npm run test:evaluate-api && npm run test:evaluate-workflow && npm run test:evaluate-tool-use && npm run test:evaluate-promptfoo && npm run test:evaluate-learned-framework && npm run test:docs-tutorial && npm run test:knowledge && npm run test:criteria-fragments && npm run test:doc-count-sources && npm run test:planning-doc-sources && npm run test:doc-counts && npm run test:doc-claim-sources && npm run test:doc-claims && npm run test:doc-invocation-entry && npm run test:doc-invocations && npm run test:doc-link-anchors && npm run test:docs-build-names && npm run test:docs-evaluate-sidebar && npm run test:docs-gap-reader && npm run test:enforce-hook && npm run test:framework-scaffold && npm run test:isolation-primitives && npm run test:atdd-isolation && npm run test:atdd-net-guard && npm run test:atdd-scoring && npm run test:atdd-workflow-guidance && npm run test:generation-healing && npm run test:framework-scaffold-install-isolation && npm run test:transcript-harness && npm run test:suite-manifest && npm run test:teach-me-testing-scoring && npm run test:teach-cli && npm run test:eval-data && npm run test:eval-atdd-data && npm run test:eval-ci-data && npm run test:eval-framework-scaffold-data && npm run test:eval-nfr-data && npm run test:nfr-validate-corpus && npm run test:nfr-evidence-guidance && npm run test:nfr-cli && npm run test:eval-test-design-data && npm run test:eval-trace-data && npm run test:eval-routing-data && npm run test:eval-routing-boundaries && npm run test:eval-routing-evidence && npm run test:eval-transcript-data && npm run test:eval-teach-me-testing-data && npm run test:eval-schemas && npm run test:eval-diagnostics && npm run test:eval-replay && npm run test:eval-quality-corpus && npm run test:schema-versions && npm run test:contract-sources && npm run test:contracts && npm run test:contract-oracles && npm run test:probe-sources && npm run test:test-design-qualification && npm run test:test-review-qualification && npm run test:trace-qualification && npm run test:nfr-qualification && npm run test:ci-qualification && npm run test:probe-corpus && npm run test:compare-dominance && npm run test:compare-eval-runs && npm run test:trial-set-scoring && npm run test:automate-cli && npm run test:automate-generation-evidence && npm run test:automate-eval-fixture && npm run test:eval-automate-data && npm run test:clock-port && npm run test:probe-conformance && npm run test:corpus-conformance && npm run test:file-system-conformance && npm run test:file-system-port && npm run test:probe-targets && npm run test:port-totality && npm run test:ci-coverage && npm run test:ci-coverage-filters && npm run test:install-actionlint && npm run test:workflows-lint && npm run test:install-linux-sandbox && npm run test:shards && npm run test:groups && npm run test:cli && npm run test:workflow-cli && npm run test:framework-cli && npm run test:test-review-pr-scope && npm run test:test-review-report && npm run test:test-review-rubric && npm run test:bmad-output-gated && npm run test:release-metadata && npm run test:release-notes && npm run test:lockfile-age && npm run test:lockfile-age-cache && npm run test:licences && npm run test:supply-chain && npm run test:boundary && npm run test:direction && npm run test:lineage && npm run test:guard-publish && npm run test:layering-boundary-lineage && npm run test:changelog && npm run test:tea-workflow-descriptions && npm run test:docs-mermaid && npm run test:llms-headroom && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:atdd-isolation": "node test/test-atdd-isolation.js",
     "test:atdd-net-guard": "node test/test-atdd-net-guard.js",
     "test:atdd-scoring": "node test/test-atdd-scoring.js",
@@ -258,7 +259,8 @@
     "test:suite-manifest": "node test/test-suite-manifest.js",
     "test:supply-chain": "node test/test-supply-chain.js",
     "test:tea-workflow-descriptions": "node test/test-tea-workflow-descriptions.js",
-    "test:teach-me-testing-scoring": "node test/test-teach-me-testing-scoring.js",
+    "test:teach-cli": "node --test test/test-teach-cli.js",
+    "test:teach-me-testing-scoring": "node test/test-teach-me-testing-scoring.js && node test/test-teach-progress-format.js",
     "test:test-design-qualification": "node test/test-test-design-qualification.js",
     "test:test-review-cli": "node test/test-test-review-cli.js",
     "test:test-review-pr-scope": "node test/test-test-review-pr-scope.js",

package/skills/bmad-teach-me-testing/steps-c/step-01-init.md

@@ -103,7 +103,7 @@ You can pause and resume anytime - your progress will be saved automatically aft
 
 ### 4. Create Initial Progress File (New Learner Only)
 
-Load {progressTemplate} and create {progressFile} with:
+Load {progressTemplate} and create {progressFile} as one YAML document. A leading `---` is optional; omit a trailing `---`, which starts another document. Write the following fields:
 
 ```yaml
 ---
@@ -193,7 +193,6 @@ lastContinued: { current_date }
 summary_generated: false
 summary_path: null
 completion_date: null
----
 ```
 
 ### 5. Proceed to Assessment (New Learner Only)

package/skills/bmad-teach-me-testing/steps-c/step-01b-continue.md

@@ -71,7 +71,7 @@ Read {progressFile} completely and extract:
 
 ### 2. Update Last Continued Timestamp
 
-Update {progressFile} frontmatter:
+Update the fields in {progressFile} and preserve one YAML document. Use the full-file progress schema; omit a trailing `---` document delimiter:
 
 - Set `lastContinued: {current_date}`
 - Keep all other fields unchanged

package/skills/bmad-teach-me-testing/steps-c/step-04-session-01.md

@@ -188,7 +188,7 @@ Display:
 
 "### ✅ Quick Knowledge Check
 
-Let me ask you 3 questions to validate your understanding. Passing score: ≥70% (2 of 3 correct)."
+Let me ask you 3 questions to validate your understanding. Passing score: ≥70% (3 of 3 correct; 2 of 3 is 66.67%)."
 
 **Question 1:**
 

package/skills/bmad-teach-me-testing/steps-c/step-04-session-02.md

@@ -288,7 +288,7 @@ Display:
 
 "### ✅ Knowledge Check
 
-3 questions to validate your understanding. Passing: ≥70% (2 of 3 correct)."
+3 questions to validate your understanding. Passing: ≥70% (3 of 3 correct; 2 of 3 is 66.67%)."
 
 **Question 1:**
 

package/skills/bmod-tea/bmod.toml

@@ -2,7 +2,7 @@
 
 [bmod]
 code = "tea"
-version = "2.0.4-next.3"
+version = "2.0.4-next.4"
 update_source = "github:bmad-code-org/bmad-method-test-architecture-enterprise/skills"
 skills = [
   "bmad-tea",