@godv61/dsh-task-engine 0.19.1 → 0.20.0

package/.p0-test.mjs

@@ -0,0 +1,292 @@
+// P0 acceptance test for dsh-task-engine 0.18.0: runs the pure engine +
+// workflows functions and the registered `dev_task` tool against an in-memory
+// fs, checking every P0 gate: capability binding, frozen snapshot, fail-closed
+// unknown flow, core-rule shadow protection, and init three-phase flow.
+import { readFileSync } from 'node:fs'
+import { registerDevTask } from './lib/dev-task.js'
+import { assertAdvance, checkFileScope, newTask, taskIdFromMessage, validateWorkflow } from './lib/engine.js'
+import {
+  FLOW_PRESETS,
+  HIGH_RISK_REQUIRED_CAPABILITIES,
+  flowSatisfies,
+  resolveFlow,
+} from './lib/workflows.js'
+
+let passed = 0
+function assert(cond, msg) {
+  if (!cond) {
+    console.error('FAIL:', msg)
+    throw new Error(msg)
+  }
+  passed++
+}
+async function assertThrows(fn, fragment, msg) {
+  try {
+    await fn()
+  } catch (err) {
+    const text = err instanceof Error ? err.message : String(err)
+    assert(text.includes(fragment), `${msg} (got: ${text})`)
+    return
+  }
+  throw new Error(`${msg}: expected throw containing "${fragment}"`)
+}
+
+function makeFs(initial = {}) {
+  const files = new Map(Object.entries(initial))
+  return {
+    async resolve(relPath, opts) {
+      const base = opts && opts.cwd ? String(opts.cwd).replace(/\\/g, '/') : ''
+      const key = base ? `${base}/${relPath}` : relPath
+      return { targetKey: key, displayPath: key }
+    },
+    async readText(target) {
+      return files.get(target.targetKey)
+    },
+    async writeText(target, content) {
+      files.set(target.targetKey, content)
+    },
+    _files: files,
+  }
+}
+function makeCtx(fs, approval) {
+  const tools = []
+  return {
+    fs,
+    tools: { register(tool) { tools.push(tool); return () => {} } },
+    get(service) {
+      if (service === 'approval') return approval
+      return undefined
+    },
+    _tools: tools,
+  }
+}
+async function registered(fs, approval) {
+  const ctx = makeCtx(fs, approval)
+  registerDevTask(ctx)
+  return ctx._tools[0].execute
+}
+const EXEC = { agent: undefined, callId: undefined, signal: undefined }
+// A tool call whose session workspace is `cwd` (the harness process directory is
+// deliberately different, exactly like a web session running in e2e-project).
+function sessionExec(cwd) {
+  return { agent: { session: { header: { cwd } } }, callId: undefined, signal: undefined }
+}
+
+// ── 1. capability derivation and high-risk binding ────────────────────────
+assert(flowSatisfies('standard', HIGH_RISK_REQUIRED_CAPABILITIES), 'standard satisfies high-risk capabilities')
+assert(!flowSatisfies('agile', HIGH_RISK_REQUIRED_CAPABILITIES), 'agile lacks a high-risk capability')
+assert(!flowSatisfies('minimal', HIGH_RISK_REQUIRED_CAPABILITIES), 'minimal lacks a high-risk capability')
+assert(FLOW_PRESETS.standard.version === 1, 'preset carries a version')
+
+// ── 2. unknown flow fails closed ───────────────────────────────────────────
+const unknown = resolveFlow('nope')
+assert(unknown.ok === false && unknown.code === 'UNKNOWN_FLOW', 'unknown flow returns UNKNOWN_FLOW')
+assert(unknown.knownFlows.includes('standard'), 'known flow list is surfaced')
+
+// ── 3. core bindings cannot be cancelled by an override ────────────────────
+const merged = resolveFlow('standard', { stage_bindings: { '开发': { rules: [] } } })
+assert(merged.ok && merged.config.stage_bindings['开发'].rules.includes('coding-conventions'),
+  'emptying a stage override keeps the core rule')
+
+// ── 4. newTask freezes the snapshot ────────────────────────────────────────
+const snapshot = { flow: 'standard', version: 1, config: FLOW_PRESETS.standard.config }
+const state = newTask({ id: 'T1', title: 'x', branch: 'main', work_size: 'standard', risk_level: 'standard', flow: snapshot })
+assert(state.flow?.flow === 'standard' && state.flow.version === 1, 'newTask stores the frozen snapshot')
+assert(state.stage === '需求评审', 'newTask starts at the frozen start stage')
+
+// ── 5. high_risk create on minimal is rejected ─────────────────────────────
+await assertThrows(
+  () => registered(makeFs({ '.dsh/eng.json': JSON.stringify({ flow: 'minimal' }) }))
+    .then(exe => exe({ operation: 'create', task_id: 'T2', title: 'x', branch: 'main', risk_level: 'high_risk' }, EXEC)),
+  'high_risk',
+  'high_risk on minimal is rejected',
+)
+
+// ── 6. a task keeps its frozen snapshot after eng.json changes ─────────────
+{
+  const fs = makeFs({ '.dsh/eng.json': JSON.stringify({ flow: 'standard' }) })
+  const exe = await registered(fs)
+  const created = await exe({ operation: 'create', task_id: 'T3', title: 'x', branch: 'main' }, EXEC)
+  assert(created.includes('需求评审'), 'standard create starts at 需求评审')
+  fs._files.set('.dsh/eng.json', JSON.stringify({ flow: 'minimal' }))
+  const status = JSON.parse(await exe({ operation: 'status', task_id: 'T3' }, EXEC))
+  assert(status.flow?.flow === 'standard' && status.flow.version === 1, 'status re-reads the frozen snapshot')
+  assert(Array.isArray(status.legal_next) && status.legal_next.includes('设计'),
+    'gates come from the frozen standard flow, not the live minimal flow')
+}
+
+// ── 7. unknown flow blocks state-changing operations ───────────────────────
+await assertThrows(
+  () => registered(makeFs({ '.dsh/eng.json': JSON.stringify({ flow: 'nope' }) }))
+    .then(exe => exe({ operation: 'create', task_id: 'X', title: 'y', branch: 'z' }, EXEC)),
+  'unknown flow',
+  'create on an unknown flow fails closed',
+)
+
+// ── 8. a file missing its flow field fails closed ──────────────────────────
+await assertThrows(
+  () => registered(makeFs({ '.dsh/eng.json': JSON.stringify({}) }))
+    .then(exe => exe({ operation: 'create', task_id: 'X', title: 'y', branch: 'z' }, EXEC)),
+  'missing a "flow" field',
+  'eng.json without a flow field is a config error',
+)
+
+// ── 9. init: inspect → propose → apply, no direct overwrite ────────────────
+{
+  const fs = makeFs()
+  const exe = await registered(fs)
+  const insp = await exe({ operation: 'init', phase: 'inspect' }, EXEC)
+  assert(insp.includes('no AGENTS.md'), 'inspect on empty project prompts a scan')
+  const prop = await exe({ operation: 'init', phase: 'propose', content: '# 项目\n示例' }, EXEC)
+  assert(prop.includes('proposed create'), 'propose previews without writing')
+  assert(fs._files.get('AGENTS.md') === undefined, 'propose writes nothing')
+  const app = await exe({ operation: 'init', phase: 'apply', content: '# 项目\n示例' }, EXEC)
+  assert(app.includes('wrote ./AGENTS.md'), 'apply writes the file')
+  assert(fs._files.get('AGENTS.md') === '# 项目\n示例', 'apply persisted the draft')
+}
+
+// ── 10. init protects an existing governance file ─────────────────────────
+{
+  const fs = makeFs({ 'AGENTS.md': '# 已有治理文件\n' })
+  const exe = await registered(fs)
+  await assertThrows(
+    () => exe({ operation: 'init', phase: 'apply', content: '# new' }, EXEC),
+    'protected',
+    'apply without overwrite on an existing file is rejected',
+  )
+  await assertThrows(
+    () => exe({ operation: 'init', phase: 'apply', content: '# new', overwrite: true }, EXEC),
+    'approval',
+    'overwrite requires an approval service',
+  )
+}
+
+// ── 11. a project cannot shadow a bundled core rule ────────────────────────
+{
+  const bundled = readFileSync('./rules/security-redlines.md', 'utf8')
+  assert(bundled.includes('服务端'), 'bundled security-redlines exists as expected')
+  const fs = makeFs({
+    '.dsh/eng.json': JSON.stringify({ flow: 'standard' }),
+    '.dsh/rules/security-redlines.md': '# 弱化的安全红线，前端校验即可',
+  })
+  const exe = await registered(fs)
+  await exe({ operation: 'create', task_id: 'T9', title: 'x', branch: 'main' }, EXEC)
+  const status = JSON.parse(await exe({ operation: 'status', task_id: 'T9' }, EXEC))
+  const sec = status.bindings.rules.find(r => r.name === 'security-redlines')
+  assert(sec !== undefined, 'security-redlines is disclosed at the start stage')
+  assert(!sec.content.includes('前端校验即可'), 'a project shadow of a core rule is ignored')
+  assert(sec.content.includes('服务端'), 'the bundled core rule body wins over a shadow')
+}
+
+// ── 12. session cwd drives every relative path (init regression) ──────────
+{
+  const cwd = 'C:/users/ggbond/.dsh-verify/e2e-project'
+  const fs = makeFs({
+    [`${cwd}/AGENTS.md`]: '# e2e 项目治理文件\n两行\n',
+    'D:/dsharness/deepseek-harness/AGENTS.md': '# DeepSeek Harness monorepo (packages/pnpm)\n',
+  })
+  const exe = await registered(fs)
+  const insp = await exe({ operation: 'init', phase: 'inspect' }, sessionExec(cwd))
+  assert(insp.includes('# e2e 项目治理文件'), 'inspect reads the session workspace AGENTS.md')
+  assert(!insp.includes('monorepo'), 'inspect does not read the harness repo AGENTS.md')
+}
+
+// ── 13. create writes the task record into the session workspace ──────────
+{
+  const cwd = 'C:/users/ggbond/.dsh-verify/e2e-project'
+  const fs = makeFs({ [`${cwd}/.dsh/eng.json`]: JSON.stringify({ flow: 'standard' }) })
+  const exe = await registered(fs)
+  await exe({ operation: 'create', task_id: 'T12', title: 'x', branch: 'main' }, sessionExec(cwd))
+  assert(fs._files.get(`${cwd}/.dsh/task-T12.json`) !== undefined, 'task record lands in the session workspace')
+  assert(fs._files.get('.dsh/task-T12.json') === undefined, 'task record does not land in the backend base')
+}
+
+// ── 14. K: artifact ids must be unique across ALL stages ────────────────────
+{
+  const withDup = { ...FLOW_PRESETS.standard.config, artifacts: [
+    { stage: '需求评审', id: 'doc', name: '需求', fields: ['scope'] },
+    { stage: '设计', id: 'doc', name: '设计', fields: ['approach'] },
+  ] }
+  const problems = validateWorkflow(withDup)
+  assert(problems.some(p => p.includes('duplicate artifact id "doc"')),
+    'cross-stage duplicate artifact id is rejected')
+}
+
+// ── 15. K: record rejects an artifact owned by another stage ─────────────────
+{
+  const fs = makeFs({ '.dsh/eng.json': JSON.stringify({ flow: 'standard' }) })
+  const exe = await registered(fs)
+  await exe({ operation: 'create', task_id: 'K1', title: 'x', branch: 'main' }, EXEC)
+  await assertThrows(
+    () => exe({ operation: 'record', task_id: 'K1', artifact: 'design', fields: { approach: 'a', risks: 'r', impact: 'i' } }, EXEC),
+    'belongs to stage',
+    'recording an artifact at a non-owning stage is rejected',
+  )
+}
+
+// ── 16. L/4.2: high-risk verification requires a REAL command receipt ────────
+{
+  const cfg = FLOW_PRESETS.standard.config
+  const receipt = overrides => ({
+    command: 'npm test', exit_code: 0, timed_out: false, aborted: false,
+    started_at: '2026-01-01T00:00:00Z', finished_at: '2026-01-01T00:00:01Z',
+    stdout: '', stderr: '', ...overrides,
+  })
+  const mk = () => {
+    const s = newTask({ id: 'L1', title: 'x', branch: 'main', work_size: 'standard', risk_level: 'high_risk', flow: snapshot })
+    s.stage = '交付'
+    return s
+  }
+  let s = mk(); s.verification = { passed: true, evidence: ['单测通过'] }
+  assert(!assertAdvance(s, '代码审核', cfg).ok, 'high_risk with text-only evidence is blocked (no command receipt)')
+  s = mk(); s.verification = { passed: true, evidence: [], receipt: receipt({}) }
+  assert(assertAdvance(s, '代码审核', cfg).ok, 'high_risk with an exit-0 receipt passes the verified gate')
+  s = mk(); s.verification = { passed: true, evidence: [], receipt: receipt({ exit_code: 1 }) }
+  assert(!assertAdvance(s, '代码审核', cfg).ok, 'high_risk with a non-zero exit receipt is blocked')
+  s = mk(); s.verification = { passed: true, evidence: [], receipt: receipt({ timed_out: true }) }
+  assert(!assertAdvance(s, '代码审核', cfg).ok, 'high_risk with a timed-out receipt is blocked')
+  s = mk(); s.verification = { passed: true, evidence: [], receipt: receipt({ aborted: true }) }
+  assert(!assertAdvance(s, '代码审核', cfg).ok, 'high_risk with an aborted receipt is blocked')
+}
+
+// ── 17. J: task id extracted from the summary (the hook uses it, not a guess) ─
+{
+  const cfg = FLOW_PRESETS.standard.config
+  assert(taskIdFromMessage('【GREET-001】【TASK】实现登录', cfg) === 'GREET-001', 'standard summary yields its task id')
+  assert(taskIdFromMessage('【GREET-001】【T1】实现登录', cfg) === 'GREET-001', 'item-label summary yields its task id')
+  assert(taskIdFromMessage('实现登录', cfg) === undefined, 'non-matching summary yields no task id')
+  assert(taskIdFromMessage('随意', FLOW_PRESETS.minimal.config) === undefined, 'pattern-less flow yields no task id')
+}
+
+// ── 18. N: engine bookkeeping files are exempt from file scope ───────────────
+{
+  const s = newTask({ id: 'N1', title: 'x', branch: 'main', work_size: 'standard', risk_level: 'standard', flow: snapshot })
+  s.files = ['src/a.ts']
+  assert(checkFileScope(s, ['src/a.ts', '.dsh/task-N1.json', '.dsh/eng.json'], FLOW_PRESETS.standard.config).ok,
+    'task record and eng.json do not violate file scope')
+  assert(!checkFileScope(s, ['src/b.ts'], FLOW_PRESETS.standard.config).ok,
+    'an out-of-scope code file is still flagged')
+}
+
+// ── 19. H/I: hook reads raw-byte paths, NUL-separated, including deletions ───
+{
+  const hook = readFileSync('./hooks/commit-msg', 'utf8')
+  assert(hook.includes('-c core.quotePath=false'), 'hook disables git octal path quoting')
+  assert(hook.includes('-z'), 'hook reads NUL-separated raw-byte paths')
+  assert(hook.includes('--diff-filter=ACMRDT'), 'hook includes deletions and type changes in the scope check')
+}
+
+// ── 20. 4.1/4.3: hook uses the frozen snapshot; writeInit guards overwrite ──
+{
+  const hook = readFileSync('./hooks/commit-msg', 'utf8')
+  assert(hook.includes('config = state.flow.config'), 'hook checks the task frozen flow snapshot')
+  assert(hook.includes('function extractTaskId'), 'hook extracts the task id independent of the live config')
+  assert(!hook.includes('const FLOWS'), 'hook bundles the single source (workflows.ts), not a hand mirror')
+}
+{
+  const controller = readFileSync('./lib/controller.js', 'utf8')
+  assert(controller.includes('AGENTS.md 已存在且受保护'), 'workbench writeInit refuses to overwrite without an explicit intent')
+  assert(controller.includes('overwrite'), 'writeInit request carries an overwrite field')
+}
+
+console.log(`\nP0 acceptance: ${passed} checks passed`)

package/README.md

@@ -9,7 +9,8 @@
 - **产物门**：每个阶段要交的产物 + 必填字段（需求说明 / 设计文档 / 评审记录…已固化在预设里），字段没填全 → 不让流转。
 - **提交门禁**：到检查点才能提交，消息必须匹配预设的提交格式，`manual` 策略永不自动提交。
 - **文件范围**：任务声明 `files`（本任务该改的文件），提交碰了范围外的文件 → 工具和 git 钩子都拒绝。
-- **skill / rule 挂载**：流程预设里每个阶段默认挂了「这个阶段用什么 skill」+「守哪条 rule」；项目可覆盖挂载，模型走到该阶段时，`dev_task` 只**渐进披露**这阶段挂载的内容，不一次性全给。内置一套通用库，也能在网页里新建自己的 skill/rule。
+- **skill / rule 挂载**：流程预设里每个阶段默认挂了「这个阶段用什么 skill」+「守哪条 rule」；项目可在节点上**追加**自己的 skill/rule（内置绑定保留、不可移除，同名会被拒、只读内置版），模型走到该阶段时，`dev_task` 只**渐进披露**这阶段挂载的内容，不一次性全给。内置一套通用库，也能在网页里新建自己的 skill/rule。
+- **边界（诚实说明）**：「需求确认」「方案确认」两扇门由**人工批准**点亮；但「实施项完成」「验证通过」「评审通过」是模型通过工具上报的状态，代码只校验这些状态在流程里自洽、格式/范围/绑定对齐，**不验证上报内容本身是否属实**——要硬保证请叠加外部 CI 或人工评审，不要把它当事实仲裁。
 
 ## 目录
 
@@ -74,7 +75,7 @@ dsh plugin --profile <name> add .
   name: '@godv61/dsh-task-engine/agent'
 ```
 
-也可重跑 `dsh-task-engine-enable` 强制重建默认的 `eng`。
+`dsh-task-engine-enable` 同样**只在 `eng` 不存在时创建**（已存在则直接退出、绝不覆盖）；要重建请先删掉 `eng` 再重跑。
 
 ## 项目配置（选流程 + 挂 skill/rule）
 
@@ -93,7 +94,7 @@ dsh plugin --profile <name> add .
 - `flow`：选一套内置流程预设 —— `standard`（需求评审→设计→开发→交付→代码审核，含产物门+确认门）/ `agile`（需求→开发→交付→审查，四阶段少产物）/ `minimal`（开发→交付，只留提交门禁）。
 - `stage_bindings`：每个节点挂哪些 skill / rule（可整体省略，省略即用该预设自带的默认绑定）。
 
-**阶段图、流转守卫、产物字段、提交规则、验证证据开关全部固化在预设里，不再手工配置**。团队要改「提交消息格式」「交付要自测」这些约定，就覆盖内置的 `code-commit`/`code-verify` skill 和 `commit-conventions` rule（正文即规范），而不是改一堆参数。
+**阶段图、流转守卫、产物字段、提交规则、验证证据开关全部固化在预设里，不再手工配置**。团队要改「提交消息格式」「交付要自测」这些约定，就新建一个项目级的新 skill/rule（用**新名字**，再挂到对应节点）——内置 skill/rule 的正文不可被同名覆盖（同名新建会被拒、解析同名只读内置版），新增的会与内置的一起挂在该节点上。
 
 `dev_task`（operation=config）随时查看当前生效配置；配置写错（未知 flow / 绑定到不存在的阶段 / 空名）会报错，不悄悄退回默认。
 
@@ -123,7 +124,7 @@ dsh plugin --profile <name> add .
 ```
 
 - **渐进披露**：模型走到某阶段时，`dev_task`（`status` / `advance`）只返回**这个阶段**挂载的 skill 名 + rule 内容；skill 用 DSH 的 `skill` 工具按名加载，rule 直接把正文给出。阶段推进到哪，才给哪。
-- **三层来源**：技能和规则都来自「内置 + 项目 + 用户」三层——内置（本包 `skills/`、`rules/`）、项目（`.dsh/skills/`、`.dsh/rules/`）、用户（`$DSH_HOME/skills/`、`$DSH_HOME/rules/`），同名时项目优先于用户优先于内置。
+- **三层来源**：技能和规则都来自「内置 + 项目 + 用户」三层——内置（本包 `skills/`、`rules/`）、项目（`.dsh/skills/`、`.dsh/rules/`）、用户（`$DSH_HOME/skills/`、`$DSH_HOME/rules/`）。**同名时内置优先**：内置 skill/rule 不可被项目/用户同名覆盖（新建同名会被拒，解析同名只读内置版）。
 - **网页新建 / 查看 / 编辑 / 删除**：工作台「技能 / 规则」标签页里可新建、查看、编辑、删除项目级/用户级 skill 和 rule（内置只能查看、不可删改）。查看时正文以 markdown **富文本**渲染在宽弹窗里；编辑时正文保持纯文本。项目级写进 `.dsh/skills|rules/`（团队共享），用户级写进 `$DSH_HOME/skills|rules/`（个人全局），写好后自动出现在挂载清单里。
 - **内置库**：6 个节点技能（`requirement-analysis` / `solution-design` / `code-implement` / `code-verify` / `code-review` / `code-commit`）+ 3 条规则（`coding-conventions` / `commit-conventions` / `security-redlines`），开箱即用；想加项目专属的，用 DSH 原生技能机制或网页新建即可。
 
@@ -172,4 +173,6 @@ dsh plugin --profile <name> add .
 - **工程可靠性加固（0.18.0）**：① 高风险任务与流程能力绑定——`high_risk` 任务只能在具备「验证门 + 文件范围 + 评审门」能力的流程创建，选 `agile`/`minimal` 直接拒绝；② 任务创建时固化流程快照（预设 id + version + 完整配置），后续 `status`/`advance`/`verify`/`review`/`commit` 一律用快照，中途改 `.dsh/eng.json` 不再漂移在途任务的门禁；③ 未知流程失败关闭——`.dsh/eng.json` 缺 `flow` 或 `flow` 不在预设里一律报错（`UNKNOWN_FLOW` / 缺字段），不再静默回退 `standard`；④ 核心 skill/rule 不可取消、不可被同名覆盖——项目阶段绑定只能追加不能移除预设自带绑定，同名规则/技能读内置版、新建同名被拒；⑤ `init` 升级 `inspect → propose → apply` 三阶段，覆盖已有 `AGENTS.md` 需人工批准。
 - **会话工作目录修复（0.18.1）**：`dev_task` 的所有文件操作此前用 `fs.resolve(相对路径)` 不带 cwd，落到了 fs 后端默认目录（DSH 进程目录）而非会话工作区——在 web 会话里会把台账、配置、`AGENTS.md`、git 钩子写到/读到错误位置。改为从 `exec.agent.session.header.cwd` 取会话工作区并传给每个解析，补 4 项回归测试。
 - **工作台项目初始化（0.19.0）**：工作台新增置顶的「项目初始化」标签页——加载展示项目根 `AGENTS.md`、一键让 AI 扫描项目生成草稿（预览后再确认写回）、支持手动编辑与覆盖；Host 控制器新增 `readInit`/`writeInit`/`generateInit` 三个 Remote，`generateInit` 通过 `ctx.llm` + 默认模型在 Host 端直接生成，复用 `dev_task init` 的 200 行硬约束。
-- **使用手册跟进（0.19.1）**：随包发布的 `docs/manual.html` 补上工作台「项目初始化」（默认置顶标签页、项目根自动发现、AI 生成 150 秒超时 + 覆盖需人工确认），第 7 节标签页从「三个」改为「五个」；删除顶层已废弃的 `USER_GUIDE.html`（v0.9.1、无引用、不随包发布），README 目录结构描述同步为五标签页。
+- **使用手册跟进（0.19.1）**：随包发布的 `docs/manual.html` 补上工作台「项目初始化」（默认置顶标签页、项目根自动发现、AI 生成 150 秒超时 + 覆盖需人工确认），第 7 节标签页从「三个」改为「五个」；安装章节补全 dsh CLI（非源码）安装方式与 pnpm 前置、`dsh plugin add` 的挂载机制；删除顶层已废弃的 `USER_GUIDE.html`（v0.9.1、无引用、不随包发布），README 目录结构描述同步为五标签页。
+- **审计修复（0.19.2）**：补齐七项——① 提交钩子 `stagedFiles` 用 `core.quotePath=false` + `-z` 按 NUL 拆分（中文文件名不再被八进制转义误拒）并补 `D`（删除范围外文件也被拦）；② 提交消息第一段改为 task id、钩子按 id 精确定位任务（不再按分支/mtime 猜，同分支多任务不再锁错）；③ artifact id 全流程唯一 + `record` 校验产物属于当前阶段（堵越阶段复用）；④ 高风险验证证据 `trim()` 后须非空（`evidence:[""]` 不再通过）；⑤ README/手册加「诚实边界」，明说验证/评审/实施项是模型自报、需人工或 CI 兜底；⑥ 文档修正优先级（内置 &gt; 用户 &gt; 项目、内置不可覆盖）与 enable 措辞，`.dsh/task-*.json`/`eng.json` 豁免文件范围门；⑦ 提交钩子改用任务快照的 frozen 配置校验（对抗任务执行中改流程导致的配置漂移）；⑧ 工作台 `writeInit` 对齐 `init` 保护（已有 `AGENTS.md` 时需显式 overwrite + 前端确认才覆盖）；⑨ `.p0-test.mjs` 纳入发布包，装包后 `npm test` 可用。新增回归测试。
+- **安全闭环（0.20.0）**：① 验证改真实命令回执——`dev_task verify` 新增 `command` 入参，引擎通过宿主 shell 服务真实运行该命令并落 `VerificationReceipt`（命令 / 退出码 / 超时 / 中止 / 起止时间 / stdout / stderr）；`high_risk` 任务的 `verified` 门改为要求回执 `exit_code === 0` 且非超时 / 中止，纯文本 `passed` 声明不再放行（常规风险仍可用 `passed` + `evidence` 文本）；② 文件范围检查补 `T` + 改用 `--name-status`——`--diff-filter=ACMRDT` 纳入类型变换，提交状态随范围拒绝一并报出，删除 / 类型变换 / 重命名的旧·新路径都受范围检查；③ 提交钩子改为从 `engine.ts` / `workflows.ts` 单一源打包生成（`build-hook.mjs`），彻底消除手写镜像漂移，未知流程在钩子侧同样 fail-closed（不再静默回退 `standard`）。

package/docs/manual.html

@@ -80,22 +80,32 @@
           <p><strong>它不是常驻程序。</strong>只有你在「工程化开发引擎」预设的会话里提出开发请求时，才触发 <code>dev_task</code> 和这套门禁；换到别的预设，流程完全不介入。</p>
         </div>
         <p>三样东西分工明确：<strong>流程预设</strong>决定「走哪条流水线、有哪些守卫」，<strong>Skill</strong> 决定「这一站做什么」，<strong>Rule</strong> 决定「这一站守什么」。任务状态单独落盘，负责「跨会话恢复到哪一步」。</p>
+        <div class="callout warn">
+          <p><strong>诚实边界：</strong>阶段流转、提交格式、文件范围、消息里的任务绑定是<b>代码硬校验</b>（不匹配直接拒绝）；<b>高风险任务的「验证通过」也是真实命令回执</b>——引擎实际运行 <code>verify</code> 命令、取退出码（<code>exit_code === 0</code> 且非超时/中止）才放行，不是模型自报。仍属模型自报、需人工或 CI 兜底的是：常规风险的验证声明、「评审通过」「实施项完成」，以及回执命令本身的覆盖面。只有「需求确认」「方案确认」两扇门由人工批准点亮。</p>
+        </div>
       </section>
 
       <section id="install">
         <h2>2. 安装与启用</h2>
-        <h3>先装 DSH（二选一）</h3>
-        <pre><code># 方式 A：npm 一条命令（需要 Node.js ≥ 22）
+        <h3>2.1 前置：Node.js ≥ 22 + pnpm</h3>
+        <pre><code>npm install -g pnpm   # dsh 的 plugin 子命令底层转发给 pnpm，必须先装</code></pre>
+        <h3>2.2 先装 DSH（三选一）</h3>
+        <pre><code># 方式 A：npm 装 CLI（非源码，推荐给使用者）
+npm install -g @deepseek-ai/dsh
+dsh web
+
+# 方式 B：npx 免安装直接跑
 npx @deepseek-ai/dsh web
 
-# 方式 B：从源码 clone
+# 方式 C：从源码 clone（开发者）
 git clone https://github.com/deepseek-ai/deepseek-harness.git
 cd deepseek-harness
 pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
-        <h3>再装引擎插件</h3>
+        <h3>2.3 把引擎插件装进 profile</h3>
         <pre><code>dsh plugin --profile web add @godv61/dsh-task-engine</code></pre>
-        <p>重启 Web 后自动完成两件事：侧边栏多出「工程流程」工作台；预设列表多出「工程化开发引擎」。</p>
-        <h3>启用</h3>
+        <p><code>dsh plugin --profile &lt;name&gt; add &lt;package&gt;</code> 会在 <code>$DSH_HOME/profiles/&lt;name&gt;/</code> 里执行 <code>pnpm add</code>，并自动识别插件声明的 <code>dsh.bundle.patch</code>，把它挂进该 profile 的插件层栈——<b>不要</b>手写 <code>npm i</code> 装到别处，那样不会挂载。</p>
+        <p>装完<b>重启 <code>dsh web</code></b> 生效，自动完成两件事：侧边栏多出「工程流程」工作台；预设列表多出「工程化开发引擎」。</p>
+        <h3>2.4 启用</h3>
         <p>新建会话 → 预设选「工程化开发引擎」。这个会话就挂上 <code>dev_task</code> + 内置技能 + 工程人设，开始按流程走。</p>
         <div class="callout"><p>想「正式开发」就选它；想「让 AI 自由探索」就选 <code>standard</code>。切换预设本身就是开关，零配置。</p></div>
       </section>
@@ -120,7 +130,7 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
               <tr><td><code>.dsh/skills/</code></td><td>项目级 skill（团队共享）</td><td>节点挂载命中时按需读取</td></tr>
               <tr><td><code>.dsh/rules/</code></td><td>项目级 rule（团队共享）</td><td>节点挂载命中时按需读取</td></tr>
               <tr><td><code>.dsh/task-*.json</code></td><td>当前任务的有效状态快照</td><td>确认、实施、验证、评审、切换阶段时更新</td></tr>
-              <tr><td><code>$DSH_HOME/skills/ · rules/</code></td><td>用户级 skill / rule</td><td>同名时优先于项目级、内置</td></tr>
+              <tr><td><code>$DSH_HOME/skills/ · rules/</code></td><td>用户级 skill / rule</td><td>同名时让位于内置（内置 &gt; 用户 &gt; 项目）</td></tr>
             </tbody>
           </table>
         </div>
@@ -157,7 +167,7 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
               <tr><td><code>requirement-analysis</code></td><td>目标、验收、非目标，落需求说明，等人确认</td><td>编码</td></tr>
               <tr><td><code>solution-design</code></td><td>最小方案、技术基线、改动点，落设计文档</td><td>实现</td></tr>
               <tr><td><code>code-implement</code></td><td>实现、做「规格 + 质量」两阶段评审，都过才标完成</td><td>无关重构</td></tr>
-              <tr><td><code>code-verify</code></td><td>按验收与风险验证、记录证据（高风险必须带证据）</td><td>掩盖失败或自动修复</td></tr>
+              <tr><td><code>code-verify</code></td><td>按验收与风险验证、记录结果（高风险必须跑真实命令回执）</td><td>掩盖失败或自动修复</td></tr>
               <tr><td><code>code-commit</code></td><td>校验阶段、范围、消息格式后提交</td><td>远程 push / 合并 / 发布</td></tr>
               <tr><td><code>code-review</code></td><td>评审变更，落结论与问题清单</td><td>代替实现或验证</td></tr>
             </tbody>
@@ -178,7 +188,7 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
             </tbody>
           </table>
         </div>
-        <p>最重要的轻量原则：团队想改「提交消息格式」「交付要自测」这类约定，直接覆盖对应 rule / skill 的正文，而不是改一堆参数。</p>
+        <p>最重要的轻量原则：团队想改「提交消息格式」「交付要自测」这类约定，新建一个项目级规则 / 技能（用<b>新名字</b>）再挂到对应节点，而不是改一堆参数；内置 skill / rule 的正文<b>不可被同名覆盖</b>。</p>
       </section>
 
       <section id="configure">
@@ -198,7 +208,7 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
   }
 }</code></pre>
         <div class="callout warn"><p>页面实时校验：挂到不存在的阶段、空名等会红字提示并置灰保存；保存前主机再校验一遍。错误的配置存不进去。</p></div>
-        <p>三层来源与优先级：同名 skill / rule，<strong>项目级 &gt; 用户级 &gt; 内置</strong>。想改内置某条，新建同名项目级版本即可顶替，内置留着兜底。</p>
+        <p>三层来源与优先级：同名 skill / rule，<strong>内置 &gt; 用户 &gt; 项目</strong>——内置不可被同名覆盖（新建同名会被拒，解析同名只读内置版）。要加团队约定，新建一个<b>不同名</b>的项目级 / 用户级资源再挂到节点上。</p>
       </section>
 
       <section id="init">
@@ -252,7 +262,7 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
               <tr><td>需求评审</td><td>拆需求、落「需求说明」</td><td>字段填全，且<b>人点「允许」确认需求</b></td></tr>
               <tr><td>设计</td><td>出最小方案、落「设计文档」</td><td>字段填全，且<b>人点「允许」确认方案</b></td></tr>
               <tr><td>开发</td><td>逐项实现，每项做规格 + 质量两阶段评审</td><td>实施项非空且全部 done（每项带两阶段评审）</td></tr>
-              <tr><td>交付</td><td>验证、记证据，按门禁提交</td><td>验证通过（高风险必须带证据）</td></tr>
+              <tr><td>交付</td><td>验证、记证据，按门禁提交</td><td>验证通过（高风险必须真实命令回执，退出码 0）</td></tr>
               <tr><td>代码审核</td><td>评审变更，落「评审记录」</td><td>结论通过且字段填全</td></tr>
               <tr><td>完成</td><td>收尾</td><td>—</td></tr>
             </tbody>
@@ -280,7 +290,7 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
               <tr><td><code>risk_level</code></td><td>standard / high_risk，决定验证强度</td></tr>
               <tr><td><code>requirement_confirmed</code></td><td>需求是否已由人确认</td></tr>
               <tr><td><code>solution_confirmed</code></td><td>方案是否已由人确认</td></tr>
-              <tr><td><code>verification</code></td><td>验证是否通过 + 证据</td></tr>
+              <tr><td><code>verification</code></td><td>验证是否通过 + 证据（高风险附真实命令回执）</td></tr>
               <tr><td><code>review</code></td><td>评审结论（通过 / 未过 + 问题）</td></tr>
               <tr><td><code>files</code></td><td>本任务允许修改的文件范围</td></tr>
               <tr><td><code>commits</code></td><td>已创建的提交记录</td></tr>
@@ -297,7 +307,7 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
           <li>实施中优先受影响模块的编译、目标测试与静态检查。</li>
           <li>差异没变时复用有效证据，不重复跑相同命令。</li>
           <li>无法联调外部系统时必须如实写「未联调」，不能把编译成功说成功能通过。</li>
-          <li><code>high_risk</code> 任务过验证门必须附证据。</li>
+          <li><code>high_risk</code> 任务过验证门必须跑真实命令回执（引擎运行命令、取退出码，非自报通过）。</li>
         </ul>
         <h3>评审</h3>
         <p>开发阶段每项做「规格 + 质量」两阶段评审，都 pass 才标 done；缺评审或任一阶段 fail 会挡住「开发 → 交付」。</p>
@@ -336,7 +346,7 @@ risk_level: high_risk   // 涉及鉴权，验证要加证据
    - 规格 ✓ 质量 ✓ → done
 
 ④ 交付
-   - 验证：跑鉴权用例，记录通过证据（high_risk 必须）。
+   - 验证：跑鉴权用例，`verify` 传真实命令（high_risk 由引擎取退出码判定）。
    - 提交：【模块】【TASK】查询接口增加权限校验（只含本任务文件）
 
 ⑤ 代码审核
@@ -352,8 +362,8 @@ risk_level: high_risk   // 涉及鉴权，验证要加证据
           <p>引擎只允许：读取仓库事实、修改<b>已确认任务范围内</b>的文件、按策略创建<b>范围受控的本地提交</b>。远程 push / 合并 / 发布、数据库写入，需人单独决定。</p>
         </div>
         <details open><summary>切换预设就是开关吗？</summary><div>是。选「工程化开发引擎」才挂 <code>dev_task</code> 和内置技能；选 <code>standard</code> 等其它预设则完全不介入。</div></details>
-        <details><summary>想改内置 skill / rule 怎么办？</summary><div>不删内置（升级又回来）。新建一个<b>同名</b>的项目级 skill / rule，系统自动用你这份，内置留着兜底。</div></details>
-        <details><summary>任务文档要不要提交？</summary><div>要。<code>.dsh/task-*.json</code> 是团队共享、跨会话恢复的任务事实，随分支提交；忽略它别人只能看到代码，看不到确认内容和进度。</div></details>
+        <details><summary>想改内置 skill / rule 怎么办？</summary><div>内置正文不可被同名覆盖（同名新建会被拒）。要加团队约定，新建一个<b>不同名</b>的项目级 skill / rule 再挂到对应节点，与内置并存。</div></details>
+        <details><summary>任务文档要不要提交？</summary><div>要。<code>.dsh/task-*.json</code> 是团队共享、跨会话恢复的任务事实，随分支提交——引擎已豁免 <code>.dsh/task-*.json</code> 与 <code>.dsh/eng.json</code>，不受文件范围门拦截；忽略它别人只能看到代码，看不到确认内容和进度。</div></details>
         <details><summary>一个会话能同时做两个需求吗？</summary><div>一个任务对应一份状态文档、一个分支。新需求保存当前进度后切新分支，切回原分支即可恢复。</div></details>
         <details><summary>提交被拒是怎么回事？</summary><div>通常是四类：没建 dev_task 任务、阶段没到提交检查点、消息格式不符、提交文件不在任务范围内。按拒绝原因修正即可。</div></details>
         <details><summary>「完成」等于上线了吗？</summary><div>不等于。<code>done</code> 只表示本地验证与必要评审通过；上线、合并、发布需人另行决定。</div></details>