@godv61/dsh-task-engine 0.24.0 → 0.25.0

package/.acceptance.mjs

@@ -1,89 +1,151 @@
-/**
- * Independent acceptance check against the corrected design.
- *
- * Reads the SHIPPED config and the built engine, not the test files, so a pass
- * here cannot come from an assertion I wrote to match my own implementation.
- */
-import { readFileSync } from 'node:fs'
-import { resolveFlow, FLOW_PRESETS } from './lib/workflows.js'
-import { validateWorkflow, bindingsForStage, completionBlockers, invalidatedBy } from './lib/engine.js'
-
-let failures = 0
-const check = (label, ok, detail = '') => {
-  console.log('  ' + (ok ? '✅' : '❌') + ' ' + label + (detail ? ' — ' + detail : ''))
-  if (!ok) failures++
-}
-
-console.log('=== 验收 1：节点只选技能，规则归技能 ===')
-for (const [id, preset] of Object.entries(FLOW_PRESETS)) {
-  for (const [stage, b] of Object.entries(preset.config.stage_bindings ?? {})) {
-    if ('rules' in b && b.rules !== undefined) {
-      check(`${id}/${stage} 无节点级规则`, false, JSON.stringify(b.rules))
-    }
-    for (const e of b.skills ?? []) {
-      if (!Array.isArray(e.rules)) check(`${id}/${stage} 技能带规则数组`, false)
-      if (!e.skill?.source) check(`${id}/${stage} 技能有来源`, false, e.skill?.name)
-    }
-  }
-}
-check('全部节点只含 skills', failures === 0)
-
-console.log('')
-console.log('=== 验收 2：同一技能在任何节点规则一致 ===')
-const bySkill = new Map()
-for (const [id, preset] of Object.entries(FLOW_PRESETS)) {
-  for (const [stage, b] of Object.entries(preset.config.stage_bindings ?? {})) {
-    for (const e of b.skills ?? []) {
-      const key = `${e.skill.source}:${e.skill.name}`
-      const sig = e.rules.map(r => `${r.source}:${r.name}`).sort().join('|')
-      if (!bySkill.has(key)) bySkill.set(key, new Set())
-      bySkill.get(key).add(sig)
-    }
-  }
-}
-for (const [skill, sigs] of bySkill) {
-  check(`${skill} 规则集唯一`, sigs.size === 1, sigs.size > 1 ? [...sigs].join(' vs ') : '')
-}
-
-console.log('')
-console.log('=== 验收 3：配置可被引擎接受 ===')
-for (const id of ['standard', 'agile', 'minimal']) {
-  const problems = validateWorkflow(resolveFlow(id, {}).config)
-  check(`${id} validateWorkflow 无问题`, problems.length === 0, problems.join('; '))
-}
-
-console.log('')
-console.log('=== 验收 4：默认配置示例与预设一致 ===')
-const doc = JSON.parse(readFileSync('defaults/eng.json', 'utf8'))
-const merged = resolveFlow('standard', { stage_bindings: doc.stage_bindings })
-check('defaults/eng.json 可解析', merged.ok)
-check('defaults/eng.json 无验证问题', validateWorkflow(merged.config).length === 0)
-
-console.log('')
-console.log('=== 验收 5：三预设都以 completed 收尾 ===')
-for (const id of ['standard', 'agile', 'minimal']) {
-  const cfg = resolveFlow(id, {}).config
-  const terminals = cfg.stages.filter(s => !cfg.transitions.some(t => t.from === s))
-  const state = {
-    stage: terminals[0], execution_version: 1,
-    items: [{ id: 'A', status: 'done', review: { spec: { outcome: 'pass' }, quality: { outcome: 'pass' } } }],
-    verification: { passed: true, evidence: [] }, commits: [],
-  }
-  const blocked = completionBlockers(state, cfg)
-  check(`${id} 未提交时不可完成`, blocked.length > 0)
-  const done = { ...state, commits: [{ label: 'TASK', hash: 'abc1234' }] }
-  check(`${id} 提交后可完成`, completionBlockers(done, cfg).length === 0)
-}
-
-console.log('')
-console.log('=== 验收 6：返工三种类型范围不同 ===')
-const r = invalidatedBy('requirement'), s = invalidatedBy('solution'), d = invalidatedBy('defect')
-check('requirement 失效需求确认', r.includes('requirement_confirmation'))
-check('solution 保留需求确认', !s.includes('requirement_confirmation'))
-check('defect 保留需求与方案确认', !d.includes('requirement_confirmation') && !d.includes('solution_confirmation'))
-check('defect 失效验证与审核', d.includes('verification') && d.includes('review'))
-check('三者范围互不相同', new Set([r.join(), s.join(), d.join()]).size === 3)
-
-console.log('')
-console.log(failures === 0 ? '✅ 全部验收项通过' : `❌ ${failures} 项未通过`)
+/**
+ * Independent acceptance check for the skeleton/recommendation design.
+ *
+ * Reads the SHIPPED config and the built engine, not the test files, so a pass
+ * cannot come from an assertion written to match the implementation.
+ *
+ * The criteria are the product principles rather than implementation details:
+ *   1. a flow is state control only — adopting a setup is a separate act
+ *   2. adoption yields a config the user fully owns, editable and removable
+ *   3. a node references skills; a rule belongs to the skill that carries it
+ *   4. nothing is merged back after adoption, and an upgrade never overwrites
+ */
+import { readFileSync } from 'node:fs'
+import { resolveFlow, FLOW_PRESETS, adoptRecommendation } from './lib/workflows.js'
+import { validateWorkflow, formatResourceRef, completionBlockers, terminalRequirements, invalidatedBy } from './lib/engine.js'
+
+let failures = 0
+const check = (label, ok, detail = '') => {
+  console.log('  ' + (ok ? '✅' : '❌') + ' ' + label + (detail ? ' — ' + detail : ''))
+  if (!ok) failures++
+}
+
+console.log('=== 1. 流程只做状态控制 ===')
+for (const [id, preset] of Object.entries(FLOW_PRESETS)) {
+  const skeleton = resolveFlow(id, { flow: id }).config
+  check(`${id} 骨架不带技能`, Object.keys(skeleton.stage_bindings ?? {}).length === 0)
+  check(`${id} 骨架不带产物`, skeleton.artifacts.length === 0)
+  check(`${id} 骨架保留状态机`, preset.config.transitions.length > 0 && preset.config.stages.length > 0)
+  check(`${id} 提交文本约定不在骨架里`, skeleton.commit.message_pattern === '', JSON.stringify(skeleton.commit.message_pattern))
+}
+// When a commit gate fires and whether the file scope is protected are flow
+// control, so they must stay on the skeleton: they are a safety floor, not a
+// writing convention, and must not disappear because a user declined a setup.
+check('standard 骨架保留提交检查点', FLOW_PRESETS.standard.config.commit.checkpoints.length > 0,
+  JSON.stringify(FLOW_PRESETS.standard.config.commit.checkpoints))
+check('standard 骨架保留文件范围保护', FLOW_PRESETS.standard.config.commit.file_scope === true)
+
+console.log('')
+console.log('=== 2. 采用是显式动作 ===')
+check('推荐配置单独存在', Object.values(FLOW_PRESETS).every(p => p.recommendation !== undefined))
+check('选流程不产生绑定', Object.keys(resolveFlow('standard', { flow: 'standard' }).config.stage_bindings ?? {}).length === 0)
+
+console.log('')
+console.log('=== 3. 采用后完全可编辑、可删除 ===')
+for (const id of ['standard', 'agile', 'minimal']) {
+  const adopted = adoptRecommendation(id)
+  check(`${id} 采用后带推荐技能`, Object.keys(adopted.stage_bindings ?? {}).length > 0)
+  const replaced = resolveFlow(id, { ...adopted, stage_bindings: {} }).config
+  check(`${id} 清空后为空（不补回）`, Object.keys(replaced.stage_bindings ?? {}).length === 0)
+  const mine = resolveFlow(id, {
+    ...adopted,
+    stage_bindings: { 开发: { skills: [{ skill: { source: 'project', name: 'mine' }, rules: [] }] } },
+  }).config
+  const dev = mine.stage_bindings['开发'].skills ?? []
+  check(`${id} 用户技能被原样采纳`, dev.length === 1 && dev[0].skill.name === 'mine',
+    JSON.stringify(dev.map(s => s.skill.name)))
+}
+
+console.log('')
+console.log('=== 4. 规则归属技能，节点只引用 ===')
+for (const id of ['standard', 'agile', 'minimal']) {
+  const cfg = resolveFlow(id, adoptRecommendation(id)).config
+  let stageRuleList = false
+  let badSkill = false
+  for (const binding of Object.values(cfg.stage_bindings ?? {})) {
+    if (binding.rules !== undefined) stageRuleList = true
+    for (const entry of binding.skills ?? []) {
+      if (!Array.isArray(entry.rules)) badSkill = true
+      if (entry.skill?.source === undefined) badSkill = true
+    }
+  }
+  check(`${id} 节点无规则列表`, !stageRuleList)
+  check(`${id} 每个技能自带规则数组`, !badSkill)
+}
+
+console.log('')
+console.log('=== 5. 同一技能引用在任何节点规则一致 ===')
+for (const id of ['standard', 'agile', 'minimal']) {
+  const cfg = resolveFlow(id, adoptRecommendation(id)).config
+  const bySkill = new Map()
+  for (const binding of Object.values(cfg.stage_bindings ?? {})) {
+    for (const entry of binding.skills ?? []) {
+      const key = formatResourceRef(entry.skill)
+      const sig = entry.rules.map(formatResourceRef).sort().join('|')
+      if (!bySkill.has(key)) bySkill.set(key, new Set())
+      bySkill.get(key).add(sig)
+    }
+  }
+  let ok = true
+  for (const [skill, sigs] of bySkill) if (sigs.size > 1) { ok = false; console.log('    ' + skill + ' 有 ' + sigs.size + ' 种规则集') }
+  check(`${id} 每个技能的规则集唯一`, ok, bySkill.size + ' 个技能')
+}
+
+console.log('')
+console.log('=== 6. 配置可被引擎接受 ===')
+for (const id of ['standard', 'agile', 'minimal']) {
+  const problems = validateWorkflow(resolveFlow(id, adoptRecommendation(id)).config)
+  check(`${id} 采用后配置无问题`, problems.length === 0, problems.join('; '))
+  const bare = validateWorkflow(resolveFlow(id, { flow: id }).config)
+  check(`${id} 裸骨架也合法`, bare.length === 0, bare.join('; '))
+}
+
+console.log('')
+console.log('=== 7. defaults/eng.json 是采用后的配置示例 ===')
+const doc = JSON.parse(readFileSync('defaults/eng.json', 'utf8'))
+const merged = resolveFlow(doc.flow, doc)
+check('defaults/eng.json 可解析', merged.ok)
+if (merged.ok) {
+  check('defaults/eng.json 无验证问题', validateWorkflow(merged.config).length === 0)
+  check('defaults/eng.json 含技能（是采用后的样子）', Object.keys(merged.config.stage_bindings ?? {}).length > 0)
+}
+
+console.log('')
+console.log('=== 8. 三预设都以 completed 收尾，且检查各自声明的节点结果 ===')
+for (const id of ['standard', 'agile', 'minimal']) {
+  const cfg = resolveFlow(id, adoptRecommendation(id)).config
+  const terminals = cfg.stages.filter(s => !cfg.transitions.some(t => t.from === s))
+  // Every conclusion a flow could ask for, so each preset is judged on what IT
+  // declared rather than on what one preset happens to need.
+  const satisfied = {
+    stage: terminals[0], execution_version: 1,
+    items: [{ id: 'A', status: 'done', review: { spec: { outcome: 'pass' }, quality: { outcome: 'pass' } } }],
+    verification: { passed: true, evidence: [] },
+    review: { outcome: 'pass' },
+    commits: [{ label: 'TASK', hash: 'abc1234' }],
+  }
+  check(`${id} 未提交不可完成`, completionBlockers({ ...satisfied, commits: [] }, cfg).length > 0)
+  check(`${id} 齐全后可完成`, completionBlockers(satisfied, cfg).length === 0,
+    JSON.stringify(completionBlockers(satisfied, cfg)))
+
+  // The result the assessment found could be missing: a flow that declares a review
+  // must not complete with the review blocked, and a flow that declares none must
+  // not be made to demand one.
+  const wantsReview = terminalRequirements(cfg).includes('review_passed')
+  const blocked = completionBlockers({ ...satisfied, review: { outcome: 'blocked' } }, cfg)
+  check(`${id} ${wantsReview ? '审核未通过不可完成' : '不发明审核要求'}`,
+    wantsReview ? blocked.some(b => b.includes('passing review')) : blocked.length === 0,
+    JSON.stringify(blocked))
+}
+
+console.log('')
+console.log('=== 9. 返工三种类型范围不同 ===')
+const r = invalidatedBy('requirement'), s = invalidatedBy('solution'), d = invalidatedBy('defect')
+check('requirement 失效需求确认', r.includes('requirement_confirmation'))
+check('solution 保留需求确认', !s.includes('requirement_confirmation'))
+check('defect 保留需求与方案确认', !d.includes('requirement_confirmation') && !d.includes('solution_confirmation'))
+check('三者范围互不相同', new Set([r.join(), s.join(), d.join()]).size === 3)
+
+console.log('')
+console.log(failures === 0 ? '✅ 全部验收项通过' : `❌ ${failures} 项未通过`)
 process.exit(failures === 0 ? 0 : 1)

package/.assessment-batch1.mjs

@@ -15,13 +15,28 @@ import assert from 'node:assert/strict'
 import { join, resolve } from 'node:path'
 import { registerDevTask } from './lib/dev-task.js'
 import { newTask, todosBlockers, completionBlockers, validateWorkflow, formatResourceRef } from './lib/engine.js'
-import { FLOW_PRESETS } from './lib/workflows.js'
+import { adoptRecommendation, FLOW_PRESETS } from './lib/workflows.js'
 import { resolveFlow } from './lib/workflows.js'
+
+/**
+ * The preset as a project would actually run it: the skeleton plus the shipped
+ * recommendation, adopted exactly the way a user adopts it. A test that asserts
+ * on bindings, commit rules or artifacts wants this, because those no longer come
+ * from the preset itself.
+ * @param {string} id - preset id.
+ * @returns {import('./lib/engine.js').WorkflowConfig} the adopted config.
+ */
+function adoptedFlow(id, extra) {
+  const base = adoptRecommendation(id)
+  if (base === undefined) throw new Error('unknown preset: ' + id)
+  return resolveFlow(id, { ...base, ...extra }).config
+}
+
 
 /** Build a fixture on one preset, mirroring .workflow-test.mjs's contract. */
 function fixture(preset = 'standard', stage, extra = {}, services = {}) {
   const cwd = resolve('test-project')
-  const config = resolveFlow(preset, {}).config
+  const config = adoptedFlow(preset)
   const state = newTask({
     id: 'LIVE-1', title: 'assessment', branch: 'test', work_size: 'standard',
     risk_level: 'standard', flow: { flow: preset, version: config.version ?? 1, config }, root: cwd,
@@ -131,7 +146,7 @@ test('P1: the agile checkpoint label must satisfy the agile message pattern', as
   const f = fixture('agile', '交付', { items: [{ id: 'A', title: 'a', status: 'done' }] })
   const status = JSON.parse(await f.call({ operation: 'status' }))
   const label = status.commit?.label
-  const pattern = resolveFlow('agile', {}).config.commit.message_pattern
+  const pattern = adoptedFlow('agile').commit.message_pattern
   assert.ok(label !== undefined, 'a commit must be due at the agile checkpoint')
   assert.match(
     `【LIVE-1】【${label}】did a thing`,
@@ -202,8 +217,8 @@ test('P2: the minimal preset reviews each item once, and still reviews it', () =
   // This earlier asserted on status.skill_blockers/commit_blockers, which never
   // contain todosBlockers output, so it passed against a completely unfixed
   // engine. Call the function under test directly instead.
-  const minimal = resolveFlow('minimal', {}).config
-  const standard = resolveFlow('standard', {}).config
+  const minimal = adoptedFlow('minimal')
+  const standard = adoptedFlow('standard')
   const specPassQualityFail = {
     items: [{ id: 'A', title: 'a', status: 'done', review: { spec: { outcome: 'pass' }, quality: { outcome: 'fail' } } }],
   }
@@ -230,7 +245,7 @@ test('P2: the three presets must not share one identical review burden', () => {
     items: [{ id: 'A', title: 'a', status: 'done', review: { spec: { outcome: 'pass' }, quality: { outcome: 'fail' } } }],
   }
   const byDepth = ['standard', 'agile', 'minimal'].map(id =>
-    todosBlockers(state, resolveFlow(id, {}).config).length)
+    todosBlockers(state, adoptedFlow(id)).length)
   assert.ok(
     byDepth[2] < byDepth[0],
     `the fast-change flow must audit less per item than the full one; got ${JSON.stringify(byDepth)}`,
@@ -267,7 +282,7 @@ test('P2: a rule a skill declares but that resolves nowhere must be reported, no
 test('batch3: a stage selects skills only, and a skill carries its own complete rule list', () => {
   // The whole point of the model: opening a skill tells you every rule it runs
   // under, and binding it anywhere does not add or override any rule.
-  const config = resolveFlow('standard', {}).config
+  const config = adoptedFlow('standard')
   for (const [stage, binding] of Object.entries(config.stage_bindings ?? {})) {
     assert.ok(
       !('rules' in binding) || binding.rules === undefined,
@@ -305,7 +320,7 @@ test('batch3: the same skill carries identical rules wherever it is bound', () =
 test('batch3: a rule shared by two skills is one resource, referenced twice', () => {
   // Reuse must not duplicate the rule body: two skills referencing one rule point
   // at the same source-qualified reference.
-  const config = resolveFlow('standard', {}).config
+  const config = adoptedFlow('standard')
   const review = config.stage_bindings['代码审核'].skills
   const reviewRules = review.find(entry => entry.skill.name === 'code-review').rules.map(formatResourceRef)
   const implementRules = config.stage_bindings['开发'].skills
@@ -344,12 +359,17 @@ test('P2: reaching the last stage is not completion for any preset', () => {
   // flow could stand on its last stage with no delivery record at all. Completion
   // is now its own checked event, shared by all three presets.
   for (const [preset, stage] of [['standard', '完成'], ['agile', '审查'], ['minimal', '交付']]) {
-    const config = resolveFlow(preset, {}).config
+    const config = adoptedFlow(preset)
     const state = {
       stage,
       execution_version: 1,
       items: [{ id: 'A', title: 'a', status: 'done', review: { spec: { outcome: 'pass' }, quality: { outcome: 'pass' } } }],
       verification: { passed: true, evidence: [] },
+      // The flows that declare a review guard need a recorded verdict. That is the
+      // point of deriving terminal requirements from the flow: standard and agile ask
+      // for one, minimal does not, so this supplies what is asked for rather than
+      // what one flow happens to need.
+      review: { outcome: 'pass' },
       commits: [],
     }
     assert.ok(
@@ -365,7 +385,7 @@ test('P2: reaching the last stage is not completion for any preset', () => {
 })
 
 test('P2: completion refuses a task that has not reached a final stage', () => {
-  const config = resolveFlow('standard', {}).config
+  const config = adoptedFlow('standard')
   const state = {
     stage: '开发',
     execution_version: 1,
@@ -381,7 +401,7 @@ test('P2: completion refuses a task that has not reached a final stage', () => {
 test('P2: a flow may declare that its delivery mode needs no commit', () => {
   // A Git commit is one delivery mode, not a universal finish line: a non-code
   // task or a project outside version control has nothing to commit.
-  const withoutCommit = { ...resolveFlow('minimal', {}).config, commit_required: false }
+  const withoutCommit = { ...adoptedFlow('minimal'), commit_required: false }
   const state = {
     stage: '交付',
     execution_version: 1,
@@ -396,7 +416,7 @@ test('P2: a flow may declare that its delivery mode needs no commit', () => {
 })
 
 test('P2: an unknown review_depth is a configuration error, not a silent downgrade', () => {
-  const config = { ...resolveFlow('minimal', {}).config, review_depth: 'thorough' }
+  const config = { ...adoptedFlow('minimal'), review_depth: 'thorough' }
   const problems = validateWorkflow(config)
   assert.ok(problems.some(p => /review_depth/u.test(p)),
     `a typo must be reported; saw ${JSON.stringify(problems)}`)

package/.e2e-presets.mjs

@@ -15,7 +15,22 @@ import assert from 'node:assert/strict'
 import { join, resolve } from 'node:path'
 import { registerDevTask } from './lib/dev-task.js'
 import { newTask } from './lib/engine.js'
-import { resolveFlow, FLOW_PRESETS } from './lib/workflows.js'
+import { adoptRecommendation, resolveFlow, FLOW_PRESETS } from './lib/workflows.js'
+
+/**
+ * The preset as a project would actually run it: the skeleton plus the shipped
+ * recommendation, adopted exactly the way a user adopts it. A test that asserts
+ * on bindings, commit rules or artifacts wants this, because those no longer come
+ * from the preset itself.
+ * @param {string} id - preset id.
+ * @returns {import('./lib/engine.js').WorkflowConfig} the adopted config.
+ */
+function adoptedFlow(id, extra) {
+  const base = adoptRecommendation(id)
+  if (base === undefined) throw new Error('unknown preset: ' + id)
+  return resolveFlow(id, { ...base, ...extra }).config
+}
+
 
 const HASH = 'abcdef1234567890'
 
@@ -26,16 +41,18 @@ const HASH = 'abcdef1234567890'
  */
 async function runPreset(preset) {
   const cwd = resolve('e2e-project')
-  const config = resolveFlow(preset, {}).config
+  const config = adoptedFlow(preset)
   const state = newTask({
     id: 'E2E-1', title: 'pipeline', branch: 'main', work_size: 'standard',
     risk_level: 'standard', flow: { flow: preset, version: FLOW_PRESETS[preset].version, config }, root: cwd,
   })
   const records = new Map([
     [join(cwd, '.dsh/task-E2E-1.json'), JSON.stringify(state)],
-    // `create` reads the project's flow from here, so the preset under test must
-    // be the project's declared flow rather than one passed to the tool.
-    [join(cwd, '.dsh/eng.json'), JSON.stringify({ flow: preset })],
+    // `create` reads the project's config from here, so this writes what a real
+    // project has after adopting the shipped recommendation: the skeleton plus its
+    // recommended skills, commit rule and artifacts. Writing only `{flow}` would
+    // describe a project that adopted nothing — a different, equally valid case.
+    [join(cwd, '.dsh/eng.json'), JSON.stringify(adoptRecommendation(preset))],
     [join(cwd, 'src/a.js'), 'source'],
   ])
   const events = []
@@ -160,7 +177,25 @@ async function runPreset(preset) {
   }
   // The terminal stage's own obligations are checked before it can be left, and
   // completion is the operation that leaves it.
+  //
+  // A flow may declare its final requirements as `completion_guards` rather than on
+  // an edge, because a terminal stage has no edge to carry them — the agile flow's
+  // 审查 IS the review. They are satisfied here, at the last stage, rather than
+  // during the loop: they describe what completion means, not how a stage is entered.
   for (const binding of config.stage_bindings?.[current().stage]?.skills ?? []) load(binding.skill.name)
+  const terminalGuards = new Set(config.completion_guards ?? [])
+  if (terminalGuards.has('todos_done') && !current().items.some(item => item.status === 'done')) {
+    await call({ operation: 'items', items: [{ id: 'A', title: 'a', status: 'doing' }] })
+    await call({ operation: 'dispatch', item_id: 'A', description: 'implemented by a worker' })
+    await call({ operation: 'review_item', item_id: 'A', spec_outcome: 'pass', quality_outcome: 'pass' })
+    await call({ operation: 'items', items: [{ id: 'A', status: 'done' }] })
+  }
+  if (terminalGuards.has('verified')) {
+    await call({ operation: 'verify', command: 'npm test', description: 'run the suite' })
+  }
+  if (terminalGuards.has('review_passed')) {
+    await call({ operation: 'review', outcome: 'pass' })
+  }
   if (config.commit.checkpoints.includes(current().stage)) {
     const status = await call({ operation: 'status' })
     await call({

package/.enforce-test.mjs

@@ -0,0 +1,139 @@
+/**
+ * The three enforcement gaps the assessment found, tested as behaviour.
+ *
+ * Each of these was previously DISCLOSED but not enforced, which is the same as not
+ * being enforced: status reported the problem and the task proceeded anyway.
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { join, resolve } from 'node:path'
+import { registerDevTask } from './lib/dev-task.js'
+import { adoptRecommendation, resolveFlow } from './lib/workflows.js'
+import { completionBlockers, terminalRequirements, resourceBlockers } from './lib/engine.js'
+
+/** A project on the standard flow, one skill carrying a project rule, at 开发. */
+async function project() {
+  const cwd = resolve('enforce-project')
+  const adopted = adoptRecommendation('standard')
+  const skills = adopted.stage_bindings['开发'].skills.map(entry => ({
+    ...entry,
+    rules: [...entry.rules, { source: 'project', name: 'mine' }],
+  }))
+  const stage_bindings = { ...adopted.stage_bindings, '开发': { skills } }
+  const records = new Map([
+    [join(cwd, '.dsh/eng.json'), JSON.stringify({ ...adopted, stage_bindings })],
+    [join(cwd, '.dsh/rules/mine.md'), 'RULE'],
+    [join(cwd, 'a.js'), 'source'],
+  ])
+  const events = []
+  let execute
+  const key = (p, options) => join(options?.cwd ?? cwd, p)
+  const fs = {
+    resolve: async (p, options) => ({ targetKey: key(p, options) }),
+    readText: async target => records.get(target.targetKey),
+    listDir: async () => [],
+    lstat: async (p, options) => records.has(key(p, options)) ? { version: 'v' } : undefined,
+    writeText: async (target, content) => { records.set(target.targetKey, content) },
+  }
+  const ctx = {
+    fs,
+    tools: { register(tool) { execute = tool.execute; return () => {} } },
+    get: name => name === 'sandboxPolicy'
+      ? { resolve: () => ({ mode: 'workspace-write', workspaceRoot: cwd, sessionId: 'e' }) }
+      : undefined,
+  }
+  registerDevTask(ctx)
+  const exec = { agent: { session: { id: 'e', header: { cwd }, snapshotEvents: () => events } }, signal: new AbortController().signal }
+  const call = async args => execute(JSON.parse(JSON.stringify({ task_id: 'E-1', ...args })), exec)
+  await call({ operation: 'create', title: 't', branch: 'main', files: ['a.js'] })
+  const state = JSON.parse(records.get(join(cwd, '.dsh/task-E-1.json')))
+  state.stage = '开发'
+  state.requirement_confirmed = true
+  state.solution_confirmed = true
+  records.set(join(cwd, '.dsh/task-E-1.json'), JSON.stringify(state))
+  const load = name => {
+    const callId = 'c' + events.length
+    events.push({ type: 'tool/call', data: { name: 'skill', callId, arguments: JSON.stringify({ name }) } })
+    events.push({ type: 'tool/result', data: { message: { content: [{ type: 'tool-result', toolCallId: callId, isError: false }] } } })
+  }
+  const current = () => JSON.parse(records.get(join(cwd, '.dsh/task-E-1.json')))
+  return { call, records, cwd, load, current, rule: () => join(cwd, '.dsh/rules/mine.md') }
+}
+
+/** Satisfy everything 开发 → 交付 needs except the resource question. */
+async function satistfyDevelopment(f) {
+  await f.call({ operation: 'items', items: [{ id: 'A', title: 'a', status: 'doing' }] })
+  await f.call({ operation: 'dispatch', item_id: 'A', description: 'd' })
+  await f.call({ operation: 'review_item', item_id: 'A', spec_outcome: 'pass', quality_outcome: 'pass' })
+  await f.call({ operation: 'items', items: [{ id: 'A', status: 'done' }] })
+  for (const entry of f.current().flow.config.stage_bindings['开发'].skills) f.load(entry.skill.name)
+}
+
+test('enforce: a task WITHOUT a snapshot cannot advance while a bound rule is unresolvable', async () => {
+  // The disclosed-but-unenforced case: status said the rule was missing and advance
+  // still succeeded, so the stage completed without the constraint.
+  const f = await project()
+  const state = f.current()
+  delete state.flow.resources
+  f.records.set(join(f.cwd, '.dsh/task-E-1.json'), JSON.stringify(state))
+  await satistfyDevelopment(f)
+
+  f.records.delete(f.rule())
+  await assert.rejects(
+    () => f.call({ operation: 'advance', target_stage: '交付' }),
+    /resolves nowhere/u,
+    'a stage whose rules cannot be resolved must not be passable',
+  )
+})
+
+test('enforce: a task WITH a snapshot still advances after its source rule is deleted', async () => {
+  // The other side of the same rule: the frozen copy IS the constraint, so a
+  // deleted source is drift to report, not a reason to block. Without this the
+  // freeze would be pointless — the task would be blocked by a file it no longer
+  // needs.
+  const f = await project()
+  await satistfyDevelopment(f)
+  f.records.delete(f.rule())
+  await f.call({ operation: 'advance', target_stage: '交付' })
+  assert.equal(f.current().stage, '交付', 'the frozen task advances on its own copy')
+})
+
+test('enforce: completion requires the review and verification the flow declared', async () => {
+  // Arriving at the last stage used to be enough. The agile flow declares a review
+  // on the way into 审查, so a blocked review must now prevent completion —
+  // without hardcoding review into flows that never asked for it.
+  const agile = resolveFlow('agile', adoptRecommendation('agile')).config
+  assert.ok(terminalRequirements(agile).length >= 0)
+  const base = {
+    stage: '审查', execution_version: 1,
+    items: [{ id: 'A', status: 'done', review: { spec: { outcome: 'pass' }, quality: { outcome: 'pass' } } }],
+    verification: { passed: true, evidence: [] },
+    commits: [{ label: 'TASK', hash: 'abc1234' }],
+  }
+  assert.deepEqual(completionBlockers({ ...base, review: { outcome: 'pass' } }, agile), [],
+    'a passing review completes')
+  const blocked = completionBlockers({ ...base, review: { outcome: 'blocked' } }, agile)
+  assert.ok(blocked.some(b => b.includes('passing review')),
+    `a blocked review must prevent completion; got ${JSON.stringify(blocked)}`)
+
+  // And a flow that declares no verification gate is not made to demand one.
+  const minimal = resolveFlow('minimal', adoptRecommendation('minimal')).config
+  const minState = {
+    stage: '交付', execution_version: 1,
+    items: [{ id: 'A', status: 'done', review: { spec: { outcome: 'pass' } } }],
+    verification: { passed: false, evidence: [] },
+    commits: [{ label: 'TASK', hash: 'abc1234' }],
+  }
+  assert.deepEqual(completionBlockers(minState, minimal), [],
+    'minimal declares no verification gate, so a non-passing verification must not block it')
+})
+
+test('enforce: the resource blocker names the stage, the reference and the fix', () => {
+  const blockers = resourceBlockers(['project:mine'], '开发')
+  assert.equal(blockers.length, 1)
+  assert.match(blockers[0], /开发/u)
+  assert.match(blockers[0], /project:mine/u)
+  assert.match(blockers[0], /Restore the file|remove the binding/u,
+    'a blocker must say what to do, not only what is wrong')
+  assert.deepEqual(resourceBlockers([], '开发'), [], 'a resolvable stage has no blocker')
+})