acmer-coach 2.3.1 → 2.5.0

package/assets/rules/coach-rules.md

@@ -9,7 +9,22 @@
 
 ### 比赛目标先于知识图
 
-* 有比赛目标时，先调 `coach_target read`，再调 `coach_focus`。没有目标时不能用
+* 按“长期能力目标 → 本次比赛目标 → 当前阶段成果 → 今天一个动作”解释取舍。
+  比赛目标不能悄悄覆盖长期目标。赛前在剩余实际容量内选择可验收的改善，赛后再按新
+  证据修订；日期只提供约束，不证明某专题该学。无法装进预算时说明暂缓什么与代价。
+* `coach_target profiles` 提供有来源和样本限制的配置，再按需设置 `profileId`。
+  provisional 表示有限样本或尚待取样，不能称官方考纲、预测本届高频专题或保证奖牌。
+  不因某知识点“低频”就永久排除，不把同一道题的某一种解法当唯一算法标签。
+* 原始 VP 判题、耗时和提交是观察；WA 不等于不会，AC 不证明独立完成。先用
+  `coach_curriculum assess` 取事实引用，再在 `coach_postmortem findings` 记录 hypothesis。
+  查代码/回放核实后才用 confirmed，引用本场真实事实并解释原因；resolved 需要独立成功
+  事实。旧文字复盘只是待核实观察。工具核对引用存在，不保证因果解释正确。
+* `coach_focus` 只汇总近30天不同场次：成功起点不算问题，重复提交/复盘不增加场次数，
+  修改旧复盘不把它变成最近发生。分数是取舍参考，不是掌握度、出题概率或奖牌概率。
+
+* 有比赛目标时，结合 `coach_target read` 和 `coach_focus` 的信息取舍；当前上下文已有
+  足够信息时不必重复查询，也不要求固定调用顺序。能力排名是参考，排在前三之外或尚未
+  映射到能力的节点可以训练，说明理由即可。没有目标时不能用
   rating、游标或地图后继猜长期方向；先建立比赛、日期、结果目标、团队模式、时间预算
   和能力优先级。
 * `coach_focus` 给的是比赛能力重点，不是知识点清单。每次训练必须说明它服务哪个能力、
@@ -19,6 +34,9 @@
   `coach_postmortem`。需要回放时先用 `coach_vp_contests` 按比赛名称选择，再调
   `coach_vp_replay`；不要让学生提供 Contest ID。VP 的读题、耗时、提交、换题和团队问题优先于 rating；没有 VP 证据时要
   明确说“尚无记录”，不能装作知道短板。手工导入仍可用 `coach_vp_import`，但不能和当前账号记录混用。
+* 同步返回 `hasMore=true` 时继续拉页，`pageCounts` 是本页条数，数组是累计缓存；
+  不把累计条数说成新增。核对回放后可用事件级 `measurements` 记录有限数值指标，
+  显式填 `passed/independent`；不要从 AC 推断零漏读或沟通良好。显式导入更新整场，保留已有题目和注解。
 * 讲知识点之前调 `coach_scope`。必须说明适用范围、延伸、反例、常见错误、迁移题和退出
   条件；工具返回“没有范围卡片”时不许凭记忆补一段看似完整的范围。
 * 训练重点是比赛能力，不是沿着地图无限往下走。阶段达到目标后可以停在当前节点，转做
@@ -28,11 +46,19 @@
 
 * 长期训练先用 `coach_curriculum read` 查看路线，再用 `assess` 查实际编排依据。
   `assess` 从 checks、代码判因、passes 和课表实际完成中给出 `id/eventId`；记录多时
-  按 `evidenceNodes` 缩小范围。**rating、节点状态、取消的卷子不能代替短板证据。**
+  按 `evidenceNodes` 或 `evidenceEventIds` 缩小范围。**rating、节点状态、取消的卷子不能代替短板证据。**
 * 建立或修订路线前核实目标、起点与可用时间。每个阶段除能力成果、节点和验收条件外，
   必须填写 `basis`、`goalContribution`、`priorityReason`、`estimatedHours`、
   `evidenceRefs`、`finding`、`kind`、`uncertainty`、`diagnosticMethod`。
   说清观察到了什么、它怎样服务目标、为何排在这里、预计投入多少，不套统一算法清单。
+* training 阶段还必须填 `exitChecks`，覆盖每个节点或能力：明确 `minEvents`，按需
+  指定 `minDistinctDays`、`independent`、`maxMinutes`，或有真实测量的 `metric/maxValue`。
+  不用一句“两场VP表现好”代替可检查条件；看 read 返回的 `exitCheckResults` 逐条解释缺口。
+  缺字段不当通过，同一事件不重复计数。旧课程先 revise 补齐，不覆盖旧训练账本。
+* verified 只证明记录日期与检测条件下的表现。隔天迁移、混合题识别和重新检测用于核对
+  保持与迁移，不能把历史一次过卷解释成永久掌握；先给未标专题的题，再看能否自选模型。
+* 讲节点优先使用 `coach_scope` 精确节点卡，按“识别条件 → 为什么成立 → 失效边界 →
+  陌生题迁移”展开。结合 recognition/proofQuestions 和原始资料，不只给算法名与模板。
 * `kind=training` 的每个节点都要对应真实证据：补短板用 `finding=gap`，引用 gap；读题、决策、团队沟通这类没有单一地图节点的阶段改用 `competencies`，引用 VP/复盘产生的能力证据；
   在已证实能力上进阶用 `finding=extension`，引用 baseline。记录指向什么由你解读，
   但**不能写一段理由替代不存在的记录**，也不能把别的节点的失败贴来凑依据。
@@ -58,8 +84,8 @@
   动作或检测卷未结束时工具会拒绝。机械门槛通过也不等于能力自动达标；
   **刷够题数、讲完内容、到了周末都不能替代能力验收。** 优先级理由仍需教学判断，
   程序没有证明这条路线教育上最优。
-* 旧 v1 路线可查看，但 `needsReview` 时不能继续执行；先 assess，再 revise 补齐当前
-  及后续阶段的依据，明确迁移 v2。已完成阶段保留，不能自动编造依据或改写旧历史。
+* 旧 v1/v2 路线可查看，但 `needsReview` 时不能继续执行；先 assess，再 revise 补齐当前
+  及后续阶段的依据和 exitChecks，明确迁移 v3。已完成阶段保留，不能自动编造依据或改写旧历史。
 * `coach_plan` 仍只排近期时间块，`coach_curriculum` 保存课程顺序与阶段目标，
   `PROGRESS.yaml` 保存实际学习/检测记录，不复制另一套掌握状态。
 
@@ -68,9 +94,10 @@
 
 下面九条是硬规则，每条都能机械检查。违反就是没做好本职工作：
 
-1. **给训练指令前，必须先调 `coach_target`/`coach_focus`，再调 `coach_next`**。
-   不许只凭 rating 或地图后继挑知识点 ——
-   它可能在地图里根本不存在，或者前置还没满足。
+1. **给训练指令前，核对目标、当前重点和地图前置**。
+   用 `coach_target`、`coach_focus`、`coach_next` 按需补足信息；上下文已有足够依据时
+   不重复读取，不规定调用顺序。不许只凭 rating 或地图后继挑知识点，
+   节点必须真实存在，前置必须满足。
 2. **每条指令必须带地图节点 id**。节点 id 只能从地图取到，
    所以这条会自动逼你先读地图。
 3. **一次只给一个动作。** 禁止候选列表、禁止「你可以考虑…」、
@@ -162,16 +189,18 @@
 
 ### 复习别把新知识挤没
 
-这套系统的价值在**往前推**，不在原地保温。一个月的表里排满复习，
-等于这个月没往前走。
+训练要改善目标比赛中的表现。新知识、复习和迁移都可能带来改善，
+安排哪一个要看目标、已有表现和投入收益。
 
 **但他自己会想先复习** —— 复习舒服（做过的东西有把握）、
 开新知识点难受（进入状态有成本）。所以这个平衡**得你把**，
 不能等他主动说"我想学新的"：
 
 * 排课时，复习块**按火候排**（放得最久的那几个才排），不是按"他提了哪个"排；
-* 比火候更靠前的是**推进**：只要他状态还行、时间够，块里就该有一个是开新知识点的；
-* 反过来说，**火候高到离谱的（放了一两个月）也不能不管** —— 那种是该重讲，不是该复习。
+* **推进不等于开新知识点**：按目标与实际表现选择新课、复习、迁移或 VP，
+  不为填课表硬开新点，也不让熟悉题反复练习代替真实改善；
+* **放了一两个月的知识点先核对保持情况**，再决定检测、复习或重讲，
+  不把间隔长直接当作已经忘光。
   * **提法按规则 3：一次一个动作** ——「这块我建议验一下，90 分钟三题，做不做？」
     并且**说清你为什么觉得该验了**（拿上面的记录当证据）。
     他说做，你才走下面三步。
@@ -315,9 +344,16 @@
   他说会了就别再给。
 * **注释密度跟他的样例走** —— 样例里注释少就少，别逐行注释。
 
-**讲完才出题**：讲完用 `coach_assign` 布置，**带上 `teachMinutes`** ——
-没有那一段它会被拒绝（新知识点不给 `teachMinutes` 就是又回到"直接出题"了）。
-讲多久**你定**，别参考任何固定值：看你判断他需要多少。
+**新课动作要留出教学时间**：用 `coach_assign` 布置时带 `teachMinutes`，
+它是计划时长，不证明已经讲过，也不证明学生理解。实际开始学习后可用 `coach_mark`
+记为 studying；是否学会仍需学生表现和检测。讲多久由你根据需要判断。
+
+**续课只留必要笔记**：发生值得接着讲的进展或中断时，用 `coach_note write` 保存
+当前判断、尚未确认之处和下一次接续点，不记录整段聊天、不每次回复都写。
+`coach_status` 和新会话状态会带上最近笔记，需要细节再用 `coach_note read`。
+引用学生回应可填 `studentQuote`；工具只核对当前会话里真实学生原话，身份和位置自动记录，
+不要让学生提供消息 ID。核对成功只证明原话存在，不证明理解正确。没有原话依据的笔记
+仍可保存，但必须当作教练判断；笔记不改游标、进度、待办或检测结果，不替代掌握证据。
 
 ⚠️ **例外：游标自己那个节点不算"新知识点"** —— 接着做，不逼你再讲一遍。
 **但例外有条件：这个节点得真讲过**（有教学痕迹）。游标可以被挪到一个
@@ -433,7 +469,8 @@
 
 ## 训练数据操作纪律（P0）
 
-* 修改训练数据（地图、进度、日程）前，必须：① 告知将改什么 ② 等确认后执行。
+* 已授权课程内的事实记录、续课笔记和做题用时正常保存，不重复要求确认。
+  替换或删除个人数据、大幅改变目标或课程时，先说明将改什么，等确认后执行。
 * 禁止擅自修改他人的训练数据。
 * 挑题之前先查 AC 记录，不重复喂已经会的题。
 
@@ -482,8 +519,8 @@
   （一个写、一个验、一个造 hack 数据）。
   末尾并行死磕多道难题是 ICPC 最常见的败因 —— 风险是最后一道都做不出。
 * 每场记一句：**题目是不是全都被读过**（读漏题比做不出更亏）。
-* **赛前 2 周不塞新技巧**：只确认已经练到"不用想"的东西 ——
-  压力下只有自动化了的技能不掉线。
+* **临近比赛通常优先巩固与模拟**：按剩余时间、掌握基础和预期收益取舍；
+  必要的新内容可安排，说明收益、风险和验收方式，不按固定两周一律禁止。
 
 ## 紧急停止（最高优先级）
 

package/dev/catalog-check.mjs

@@ -0,0 +1,74 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import YAML from 'yaml'
+
+const knowledge = new URL('../assets/knowledge/', import.meta.url)
+const read = name => YAML.parse(readFileSync(new URL(name, knowledge), 'utf8'))
+const mapIds = new Set(read('MAP.yaml').nodes.map(node => node.id))
+const competencies = read('COMPETENCIES.yaml').competencies
+
+function sources(value, label) {
+  assert.ok(Array.isArray(value) && value.length > 0, `${label}: sources required`)
+  for (const source of value) {
+    assert.ok(typeof source.title === 'string' && source.title.trim(), `${label}: source title required`)
+    const url = new URL(source.url)
+    assert.equal(url.protocol, 'https:', `${label}: public HTTPS source required`)
+    assert.ok(!url.username && !url.password && !url.search, `${label}: no account credentials or query data`)
+    assert.ok(url.pathname !== '/', `${label}: link to evidence, not a homepage`)
+  }
+}
+
+function textList(value, label) {
+  assert.ok(Array.isArray(value) && value.length > 0, `${label}: nonempty list required`)
+  assert.ok(value.every(item => typeof item === 'string' && item.trim()), `${label}: text required`)
+}
+
+test('node teaching cards use exact map nodes and contain sourced transfer boundaries', () => {
+  const catalog = read('NODE_SCOPES.yaml')
+  assert.equal(catalog.version, 1)
+  assert.ok(catalog.nodes.length >= 12)
+  assert.equal(new Set(catalog.nodes.map(card => card.id)).size, catalog.nodes.length)
+  for (const card of catalog.nodes) {
+    assert.ok(mapIds.has(card.id), `${card.id}: unknown MAP node`)
+    assert.ok(card.title && card.contestUse)
+    for (const field of ['recognition', 'proofQuestions', 'appliesTo', 'extensions', 'notFor', 'commonFailures', 'transferProblems', 'exitEvidence']) {
+      textList(card[field], `${card.id}.${field}`)
+    }
+    sources(card.sources, card.id)
+  }
+  for (const id of ['最短路', '强连通分量', '线段树', '动态规划基础']) {
+    assert.ok(catalog.nodes.some(card => card.id === id), `${id}: important boundary card required`)
+  }
+})
+
+test('contest profiles identify sampling limits and use only existing competencies', () => {
+  const catalog = read('CONTEST_PROFILES.yaml')
+  const competencyIds = new Set(competencies.map(card => card.id))
+  assert.equal(catalog.version, 1)
+  assert.ok(catalog.profiles.length >= 3)
+  assert.equal(new Set(catalog.profiles.map(profile => profile.id)).size, catalog.profiles.length)
+  for (const profile of catalog.profiles) {
+    assert.ok(profile.title && profile.scope)
+    assert.ok(['provisional', 'reviewed'].includes(profile.status))
+    textList(profile.selectionGuidance, `${profile.id}.selectionGuidance`)
+    textList(profile.limitations, `${profile.id}.limitations`)
+    assert.ok(profile.competencyIds.length > 0)
+    for (const id of profile.competencyIds) assert.ok(competencyIds.has(id), `${profile.id}: unknown ${id}`)
+    sources(profile.sources, profile.id)
+    assert.match(profile.limitations.join(' '), /样本|采样|未核验/)
+    assert.doesNotMatch(JSON.stringify(profile), /金牌.*(?:必须|至少)\s*\d+\s*题|必考|命中率/)
+  }
+  const xian = catalog.profiles.find(profile => profile.id === 'xian-pending')
+  assert.ok(xian)
+  assert.equal(xian.status, 'provisional')
+  assert.match(xian.limitations.join(' '), /不是.*考纲|不能.*预测/)
+})
+
+test('general competency mappings reference real nodes and disclose their sources', () => {
+  assert.equal(new Set(competencies.map(card => card.id)).size, competencies.length)
+  for (const card of competencies) {
+    for (const id of card.nodes) assert.ok(mapIds.has(id), `${card.id}: unknown MAP node ${id}`)
+    sources(card.sources, card.id)
+  }
+})

package/dev/coaching-contract-check.mjs

@@ -0,0 +1,219 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+function shape(schema, value) {
+  if (schema.type === 'object') {
+    assert.ok(value && typeof value === 'object' && !Array.isArray(value))
+    if (schema.additionalProperties === false) for (const key of Object.keys(value)) assert.ok(key in schema.properties, `unexpected field ${key}`)
+    for (const [key, field] of Object.entries(schema.properties ?? {})) {
+      if (field.required === true || (Array.isArray(schema.required) && schema.required.includes(key))) assert.ok(key in value, `missing field ${key}`)
+      if (key in value) shape(field, value[key])
+    }
+  } else if (schema.type === 'array') {
+    assert.ok(Array.isArray(value))
+    if (schema.items) value.forEach(item => shape(schema.items, item))
+  } else if (schema.type === 'integer') assert.ok(Number.isInteger(value))
+  else assert.equal(typeof value, schema.type)
+}
+
+test('registered coaching tools expose cited findings, sourced teaching and complete refusal shapes', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'coach-contract-'))
+  const previous = { data: process.env.COACH_DATA_DIR, db: process.env.COACH_DB }
+  try {
+    writeFileSync(join(dir, 'MAP.yaml'), 'meta: {version: 1}\nnodes: []\n')
+    process.env.COACH_DATA_DIR = dir
+    process.env.COACH_DB = join(dir, 'unused.db')
+    const { apply } = await import('../index.js?coaching-contract')
+    const tools = new Map()
+    apply({ tools: { register: tool => tools.set(tool.name, tool) }, inject() {}, on() {} })
+    const call = async (name, args) => {
+      const tool = tools.get(name)
+      const result = await tool.execute(args)
+      shape(tool.output.schema, result)
+      return result
+    }
+    assert.ok(tools.get('coach_postmortem').parameters.properties.findings)
+    assert.ok(tools.get('coach_focus').output.schema.properties.profile.properties?.id, 'SDK needs explicit nested profile fields')
+    assert.ok(tools.get('coach_vp_import').parameters.properties.events.items.properties.measurements)
+    assert.equal((await call('coach_grade', { results: [] })).ok, false, 'an absent paper has a complete refusal shape')
+    assert.ok((await call('coach_target', { action: 'profiles' })).availableProfiles.length)
+    const missing = await call('coach_postmortem', { eventId: 'unknown', findings: [] })
+    assert.equal(missing.ok, false)
+    const target = await call('coach_target', { action: 'set', expectedRevision: 0, contest: '样本训练', date: '2026-10-17', result: '稳定发挥', weeklyHours: 25,
+      priorities: [{ id: 'graph-modeling', weight: 10 }] })
+    assert.equal(target.ok, true, target.reject)
+    await call('coach_vp_import', { events: [{ eventId: 'vp-contract', contest: 'VP', date: '2026-10-10', problems: [{ problemId: 'A', status: 'WA' }] }] })
+    const facts = await call('coach_curriculum', { action: 'assess' })
+    const fact = facts.evidence.find(entry => entry.source === 'vp')
+    assert.ok(fact)
+    const saved = await call('coach_postmortem', { eventId: 'vp-contract', findings: [{ competency: 'graph-modeling', status: 'confirmed',
+      cause: '对照题面和代码确认建图方向写反了', evidenceRefs: [fact.id] }] })
+    assert.equal(saved.ok, true, saved.reject)
+    const focus = await call('coach_focus', {})
+    assert.equal(focus.focus[0].gapCount, 1)
+    assert.match(focus.text, /已确认|确认短板/)
+    const measurementImport = await call('coach_vp_import', { events: [{ eventId: 'measured-contract', contest: 'VP', date: '2026-10-10',
+      problems: [{ problemId: 'A', status: 'AC' }], measurements: [{ competency: 'contest-reading', metric: 'missed-reading', value: 0, passed: true, independent: true }] }] })
+    assert.equal(measurementImport.ok, true, measurementImport.reject)
+    const measured = await call('coach_curriculum', { action: 'assess', evidenceEventIds: ['measured-contract'] })
+    assert.equal(measured.evidence.find(entry => entry.metric === 'missed-reading')?.value, 0)
+    const gap = (await call('coach_curriculum', { action: 'assess', evidenceEventIds: ['vp-contract'] })).evidence.find(entry => entry.signal === 'gap')
+    const created = await call('coach_curriculum', { action: 'create', expectedRevision: 0, goal: '区域赛稳定建图', reason: '针对已经确认的建图错误，用两场零错误指标验收', phases: [{
+      id: 'graph-measured', title: '稳定建图', kind: 'training', finding: 'gap', nodes: [], competencies: ['graph-modeling'],
+      outcome: '两场不同的VP都能独立正确建模', exitCriteria: '两场独立验收无建模错误',
+      basis: '对照题面和代码已确认建图方向错误', goalContribution: '减少区域赛建模题错误提交', priorityReason: '现有事实显示建模方向错误需要先修', estimatedHours: 5,
+      evidenceRefs: [gap.id], uncertainty: '', diagnosticMethod: '', exitChecks: [{ competency: 'graph-modeling', minEvents: 2, independent: true, metric: 'model-errors', maxValue: 0 }],
+    }] })
+    assert.equal(created.ok, true, created.reject)
+    const now = new Date()
+    const date = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+    for (let i = 0; i < 2; i++) {
+      assert.equal((await call('coach_vp_import', { events: [{ eventId: `metric-exit-${i}`, contest: 'VP', date, problems: [{ problemId: 'B', status: 'AC' }],
+        measurements: [{ competency: 'graph-modeling', metric: 'model-errors', value: 0, passed: true, independent: true, occurredAt: new Date().toISOString() }] }] })).ok, true)
+      const state = await call('coach_curriculum', { action: 'read' })
+      assert.equal(state.exitCheckResults[0].matchedEvents, i + 1)
+      if (i === 0) assert.equal((await call('coach_curriculum', { action: 'advance', expectedRevision: state.revision, reason: '只有一场，不能通过两场的验收条件' })).ok, false)
+    }
+    const finished = await call('coach_curriculum', { action: 'advance', expectedRevision: created.revision, reason: '两场不同的新VP都有独立且已验收的零建模错误测量' })
+    assert.equal(finished.status, 'complete', finished.reject)
+    const scope = await call('coach_scope', { id: '最短路' })
+    assert.equal(scope.id, '最短路')
+    assert.ok(scope.sources.length)
+    assert.ok(scope.recognition.length)
+    await call('coach_scope', { id: '不存在的卡片' })
+  } finally {
+    for (const [key, value] of [['COACH_DATA_DIR', previous.data], ['COACH_DB', previous.db]]) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('a planned lecture is not reported as past teaching', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'coach-lecture-plan-'))
+  const previous = { data: process.env.COACH_DATA_DIR, db: process.env.COACH_DB }
+  try {
+    writeFileSync(join(dir, 'MAP.yaml'), 'meta: {version: 1}\nnodes:\n  - {id: A, name: 基础, depends: []}\n  - {id: B, name: 新课, depends: [A]}\n')
+    writeFileSync(join(dir, 'PROGRESS.yaml'), 'version: 1\ncursor: A\nnodes:\n  A: {status: learned}\n')
+    process.env.COACH_DATA_DIR = dir
+    process.env.COACH_DB = join(dir, 'unused.db')
+    const { apply } = await import('../index.js?lecture-plan-contract')
+    const tools = new Map()
+    apply({ tools: { register: tool => tools.set(tool.name, tool) }, inject() {}, on() {} })
+    const assigned = await tools.get('coach_assign').execute({ node: 'B', deliverable: '独立写出状态与转移', teachMinutes: 20, why: '先解释状态为何保留这些信息' })
+    assert.equal(assigned.accepted, true, assigned.reject)
+    assert.equal((await tools.get('coach_set_cursor').execute({ node: 'B' })).ok, true)
+    const status = await tools.get('coach_status').execute({})
+    assert.equal(status.cursorTaught, '', 'planning teaching must not create a teaching date')
+    assert.equal(status.pendingActions.find(item => item.node === 'B').teachMinutes, 20)
+  } finally {
+    for (const [key, value] of [['COACH_DATA_DIR', previous.data], ['COACH_DB', previous.db]]) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('teaching notes survive reload, reach the native hook and never certify mastery', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'coach-note-contract-'))
+  const previous = { data: process.env.COACH_DATA_DIR, db: process.env.COACH_DB }
+  try {
+    writeFileSync(join(dir, 'MAP.yaml'), 'meta: {version: 1}\nnodes:\n  - {id: A, name: 基础, depends: []}\n')
+    writeFileSync(join(dir, 'PROGRESS.yaml'), 'version: 1\ncursor: A\nnodes: {}\n')
+    process.env.COACH_DATA_DIR = dir
+    process.env.COACH_DB = join(dir, 'unused.db')
+    const quote = '这里的状态只需要保留容量，不需要保留选取顺序。'
+    const query = { readSession: async (id) => {
+      assert.equal(id, 'session-1')
+      return { session: { id }, inheritedEventCount: 0, events: [{ type: 'user/message', seq: 7, data: {
+        id: 'message-7', role: 'user', source: { kind: 'user' }, content: [{ type: 'text', text: quote }],
+      } }] }
+    } }
+    const register = async (suffix) => {
+      const tools = new Map(), hooks = new Map()
+      const { apply } = await import(`../index.js?note-contract-${suffix}`)
+      apply({ tools: { register: tool => tools.set(tool.name, tool) }, inject() {},
+        get: service => service === 'sessionQuery' ? query : undefined,
+        on: (event, handler) => hooks.set(event, handler) })
+      return { tools, hooks }
+    }
+    const first = await register('first')
+    const note = first.tools.get('coach_note')
+    assert.ok(note, 'one native tool must expose teaching continuation')
+    const exec = { agent: { session: { id: 'session-1' } } }
+    const plain = await note.execute({ action: 'write', summary: '准备续讲状态含义；尚未核对学生回应', nextStep: '先查看已有的课堂上下文' })
+    shape(note.output.schema, plain)
+    assert.equal(plain.ok, true, plain.reject)
+    assert.ok(!('studentEvidence' in plain.notes[0]), 'unquoted notes do not invent student evidence')
+    const saved = await note.execute({ action: 'write', summary: '学生能解释容量维，但迁移能力尚未核对', nextStep: '用另一个背包变式确认状态含义', studentQuote: quote }, exec)
+    shape(note.output.schema, saved)
+    assert.equal(saved.ok, true, saved.reject)
+    assert.equal(saved.notes.at(-1).studentEvidence.messageId, 'message-7')
+    const bad = await note.execute({ action: 'write', summary: '不存在的回应', nextStep: '继续核对', studentQuote: '这句话不在学生的消息中' }, exec)
+    shape(note.output.schema, bad)
+    assert.equal(bad.ok, false)
+    const second = await register('reload')
+    const read = await second.tools.get('coach_note').execute({ action: 'read' })
+    shape(second.tools.get('coach_note').output.schema, read)
+    assert.deepEqual(read.notes, saved.notes)
+    assert.equal(read.total, 2)
+    const status = await second.tools.get('coach_status').execute({})
+    shape(second.tools.get('coach_status').output.schema, status)
+    assert.equal(status.verifiedCount, 0)
+    assert.equal(status.learnedCount, 0)
+    assert.equal(status.cursorTaught, '', 'even a real student quote cannot become a teaching/contact certificate')
+    assert.match(status.teachingContext, /背包变式/)
+    const hook = second.hooks.get('agent/pre-step')
+    const decision = { kind: 'enter', messages: [] }
+    const injected = await hook({ step: 1, messages: [] }, async () => decision)
+    const message = injected.messages.at(-1)
+    assert.equal(message.source.kind, 'plugin:acmer-coach', 'format v4 requires producer-owned source kind')
+    assert.ok(message.content.some(block => block.type === 'text' && block.text.includes('背包变式')))
+    assert.deepEqual(await hook({ step: 2, messages: [] }, async () => decision), decision)
+  } finally {
+    for (const [key, value] of [['COACH_DATA_DIR', previous.data], ['COACH_DB', previous.db]]) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('continuation follows a noted unfinished lesson while the cursor stays on its prerequisite', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'coach-note-pending-'))
+  const previous = { data: process.env.COACH_DATA_DIR, db: process.env.COACH_DB }
+  try {
+    writeFileSync(join(dir, 'MAP.yaml'), 'meta: {version: 1}\nnodes:\n  - {id: A, name: 基础, depends: []}\n  - {id: B, name: 新课, depends: [A]}\n')
+    writeFileSync(join(dir, 'PROGRESS.yaml'), 'version: 1\ncursor: A\nnodes:\n  A: {status: learned}\n')
+    process.env.COACH_DATA_DIR = dir
+    process.env.COACH_DB = join(dir, 'unused.db')
+    const tools = new Map(), hooks = new Map()
+    const { apply } = await import('../index.js?note-pending-contract')
+    apply({ tools: { register: tool => tools.set(tool.name, tool) }, inject() {}, on: (event, handler) => hooks.set(event, handler) })
+    const assigned = await tools.get('coach_assign').execute({ node: 'B', deliverable: '解释状态含义', teachMinutes: 20, why: '沿着已学前置开始新课' })
+    assert.equal(assigned.accepted, true, assigned.reject)
+    assert.equal((await tools.get('coach_note').execute({ action: 'write', node: 'B', summary: '状态含义已解释，尚未检查学生回应', nextStep: '继续核对容量维度' })).ok, true)
+    const status = await tools.get('coach_status').execute({})
+    assert.equal(status.cursor, 'A', 'showing continuity must not move the cursor')
+    assert.match(status.teachingContext, /容量维度/)
+    const latest = await tools.get('coach_note').execute({ action: 'read' })
+    assert.equal(latest.node, 'B')
+    assert.equal(latest.total, 1)
+    const explicit = await tools.get('coach_note').execute({ action: 'read', node: 'A' })
+    assert.equal(explicit.node, 'A', 'explicit node selection overrides the context fallback')
+    assert.equal(explicit.total, 0)
+    const injected = await hooks.get('agent/pre-step')({ step: 1, messages: [] }, async () => ({ kind: 'enter', messages: [] }))
+    assert.ok(injected.messages.at(-1).content.some(block => block.type === 'text' && block.text.includes('容量维度')))
+  } finally {
+    for (const [key, value] of [['COACH_DATA_DIR', previous.data], ['COACH_DB', previous.db]]) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    rmSync(dir, { recursive: true, force: true })
+  }
+})