@godv61/dsh-task-engine 0.23.9 → 0.25.0

package/.e2e-presets.mjs

@@ -0,0 +1,230 @@
+/**
+ * End-to-end tool-chain regression over the three presets.
+ *
+ * Drives the REAL built `dev_task` tool — create, skill loading, artifact
+ * recording, item review, verification, review, commit, completion — through an
+ * in-memory fs, so it exercises the same code path the model does rather than
+ * asserting on source text or calling engine helpers directly.
+ *
+ * Two things the assessment asks for and this does NOT provide: a real Harness
+ * Web session, and a real `git commit`. Those are reported separately as
+ * outstanding; nothing here claims to replace them.
+ */
+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 { newTask } from './lib/engine.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'
+
+/**
+ * One preset driven from creation to completion.
+ * @param preset - the preset id to run.
+ * @returns the step log plus the final state, so the test can assert on both.
+ */
+async function runPreset(preset) {
+  const cwd = resolve('e2e-project')
+  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 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 = []
+  const session = { id: 'e2e', header: { cwd }, snapshotEvents: () => events }
+  const abort = new AbortController()
+  let execute
+  let lastMessage = ''
+  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 () => [...records.keys()].filter(p => /task-.+\.json$/.test(p)).map(p => ({ name: p.split(/[\\/]/).at(-1) })),
+    lstat: async (p, options) => records.has(key(p, options)) ? { version: 'v' } : undefined,
+    writeText: async (target, content) => { records.set(target.targetKey, content) },
+  }
+  const approvals = []
+  const ctx = {
+    fs,
+    tools: { register(tool) { execute = tool.execute; return () => {} } },
+    get(name) {
+      if (name === 'sandboxPolicy') return { resolve: () => ({ mode: 'workspace-write', workspaceRoot: cwd, sessionId: 'e2e' }) }
+      // The confirmation guards require a human decision; a stub stands in for the
+      // human here and records what it was asked, so the test can show the guard
+      // actually consulted it rather than being bypassed. The verdict is the
+      // protocol's string value, not a boolean.
+      if (name === 'approval') return {
+        async request(request) { approvals.push(request); return 'allowed-once' },
+      }
+      if (name === 'shell') return {
+        resolve: request => request,
+        async run(request) {
+          const isLog = request.command.includes('log -1')
+          return {
+            exitCode: 0, timedOut: false, aborted: false,
+            sandbox: { mode: 'workspace-write', denied: false },
+            stdout: { text: isLog ? `${HASH}\n${lastMessage}\n\nsrc/a.js\n` : 'checks passed' },
+            stderr: { text: '' },
+          }
+        },
+      }
+      return undefined
+    },
+  }
+  registerDevTask(ctx)
+  const exec = { agent: { session }, signal: abort.signal }
+  const call = async args => {
+    if (args.message !== undefined) lastMessage = args.message
+    const text = await execute(JSON.parse(JSON.stringify({ task_id: 'E2E-1', ...args })), exec)
+    return args.operation === 'status' ? JSON.parse(text) : text
+  }
+  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-E2E-1.json')))
+
+  const steps = []
+  await call({ operation: 'create', title: 'pipeline', branch: 'main', files: ['src/a.js'] })
+  steps.push('create')
+
+  for (let hop = 0; hop < 14; hop++) {
+    const snapshot = current()
+    const outgoing = config.transitions.filter(transition => transition.from === snapshot.stage)
+    if (outgoing.length === 0) break
+
+    // Satisfy whatever the stage's outgoing edges need.
+    const needed = new Set(outgoing.flatMap(transition => transition.requires ?? []))
+    if (needed.has('todos_done')) {
+      // Items are reviewed through the dedicated operation; `items` only carries
+      // status, and the review verdicts are recorded against the item by id.
+      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' }] })
+    }
+    // Confirmation guards are satisfied by a human decision routed through the
+    // approval service; the tool refuses to let the model assert them itself.
+    if (needed.has('requirement_confirmation') && !snapshot.requirement_confirmed) {
+      await call({ operation: 'config', confirmations: ['requirement_confirmation'] })
+    }
+    if (needed.has('solution_confirmation') && !snapshot.solution_confirmed) {
+      await call({ operation: 'config', confirmations: ['solution_confirmation'] })
+    }
+    if (needed.has('verified')) {
+      await call({ operation: 'verify', command: 'npm test', description: 'run the suite' })
+    }
+    if (needed.has('review_passed')) {
+      await call({ operation: 'review', outcome: 'pass' })
+    }
+    for (const artifact of config.artifacts.filter(a => a.stage === snapshot.stage)) {
+      const fields = {}
+      for (const field of artifact.fields) fields[field] = 'recorded'
+      await call({ operation: 'record', artifact: artifact.id, fields })
+    }
+    // Obligations cover the current stage AND the stage being entered, so both
+    // sets are loaded. This mirrors the disclosure the model follows.
+    for (const obligated of new Set([snapshot.stage, ...outgoing.map(t => t.to)])) {
+      for (const binding of config.stage_bindings?.[obligated]?.skills ?? []) load(binding.skill.name)
+    }
+
+    if (config.commit.checkpoints.includes(snapshot.stage)) {
+      const status = await call({ operation: 'status' })
+      await call({
+        operation: 'commit', files: ['src/a.js'], hash: HASH,
+        message: `【E2E-1】【${status.commit?.label ?? 'TASK'}】deliver the stage`,
+      })
+    }
+
+    const target = outgoing[0].to
+    // The target stage's skills must be loaded before the move, because leaving a
+    // stage checks the obligations of the stage being entered. This mirrors what
+    // the disclosure tells the model to do.
+    for (const binding of config.stage_bindings?.[target]?.skills ?? []) load(binding.skill.name)
+    await call({ operation: 'advance', target_stage: target })
+    steps.push(`${snapshot.stage}→${target}`)
+  }
+
+  const terminal = config.stages.filter(stage => !config.transitions.some(t => t.from === stage))
+  if (!terminal.includes(current().stage)) {
+    return { steps, approvals, final: current(), completed: false, blocked: `stopped at ${current().stage}` }
+  }
+  // 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({
+      operation: 'commit', files: ['src/a.js'], hash: HASH,
+      message: `【E2E-1】【${status.commit?.label ?? 'TASK'}】deliver the stage`,
+    })
+  }
+  await call({ operation: 'complete' })
+  return { steps, approvals, final: current(), completed: true, blocked: null }
+}
+
+test('e2e: every preset can be driven from creation to completion through the real tool', async () => {
+  for (const preset of ['standard', 'agile', 'minimal']) {
+    const run = await runPreset(preset)
+    assert.equal(
+      run.completed, true,
+      `${preset} must reach completion; ${run.blocked ?? ''} steps=${run.steps.join(' ')}`,
+    )
+    assert.ok(run.final.completed !== undefined, `${preset} must record its completion`)
+    assert.ok(run.steps.length >= 2, `${preset} must traverse at least one edge`)
+  }
+})
+
+test('e2e: a preset that requires a commit cannot complete without one', async () => {
+  // The completion check is the thing that catches minimal, whose final stage is
+  // also its checkpoint and therefore never fires the "commit before leaving"
+  // rule. Driving it through the tool must refuse completion without a commit.
+  const run = await runPreset('minimal')
+  assert.equal(run.completed, true)
+  assert.ok(run.final.commits.length > 0,
+    'reaching completion means the delivery record exists, not merely that the last stage was reached')
+})

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')
+})

package/.evidence-test.mjs

@@ -0,0 +1,119 @@
+/**
+ * Evidence kinds: a skill is judged against the proof it actually declares.
+ *
+ * Demanding a "real validation command" from every non-core skill forced an
+ * irrelevant command from a requirement or design skill, whose output is a
+ * document. The evidence existed — in another form.
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { needsSkillReceipt, skillBlockers } from './lib/skill-audit.js'
+import { adoptRecommendation, resolveFlow } from './lib/workflows.js'
+
+/** A session that has loaded the named skills. */
+function sessionWith(names) {
+  const events = []
+  for (const name of names) {
+    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 }] } } })
+  }
+  return { id: 's', snapshotEvents: () => events }
+}
+
+/** A standard-flow config with one extra skill on 开发 carrying the given evidence. */
+function withEvidence(evidence) {
+  const adopted = adoptRecommendation('standard')
+  const skills = [...adopted.stage_bindings['开发'].skills, { skill: { source: 'project', name: 'doc-skill' }, rules: [], ...(evidence !== undefined ? { evidence } : {}) }]
+  return resolveFlow('standard', { ...adopted, stage_bindings: { ...adopted.stage_bindings, '开发': { skills } } }).config
+}
+
+/** A task at 开发 with everything else satisfied. */
+function state(extra = {}) {
+  return {
+    schema: 1, id: 'E-1', title: 't', branch: 'main', work_size: 'standard', risk_level: 'standard',
+    stage: '开发', execution_version: 1,
+    requirement_confirmed: true, solution_confirmed: true,
+    items: [], artifacts: {}, files: [], commits: [],
+    verification: { passed: false, evidence: [] },
+    review: { outcome: 'pending' },
+    ...extra,
+  }
+}
+
+test('evidence: needsSkillReceipt honours a declared non-command kind', () => {
+  // Core skills keep their exemption; a declared kind overrides the default.
+  assert.equal(needsSkillReceipt('code-implement'), false, 'a core skill owes no separate receipt')
+  assert.equal(needsSkillReceipt('doc-skill'), true, 'an undeclared extra skill defaults to a command receipt')
+  assert.equal(needsSkillReceipt('doc-skill', 'command'), true)
+  assert.equal(needsSkillReceipt('doc-skill', 'artifact'), false)
+  assert.equal(needsSkillReceipt('doc-skill', 'review'), false)
+  assert.equal(needsSkillReceipt('doc-skill', 'manual'), false)
+  assert.equal(needsSkillReceipt('doc-skill', 'none'), false)
+})
+
+test('evidence: a document-producing skill is satisfied by a recorded artifact', () => {
+  // The blocker is the point: without an artifact it blocks, and with one it does
+  // not — so the declared kind is genuinely enforced rather than merely accepted.
+  //
+  // Mounted on 设计, which the standard flow declares an artifact for. A stage with
+  // no declared artifact has nothing to satisfy artifact evidence against, and the
+  // audit deliberately stays silent there rather than inventing a requirement.
+  const adopted = adoptRecommendation('standard')
+  const config = resolveFlow('standard', {
+    ...adopted,
+    stage_bindings: {
+      ...adopted.stage_bindings,
+      '设计': { skills: [{ skill: { source: 'project', name: 'doc-skill' }, rules: [], evidence: 'artifact' }] },
+    },
+  }).config
+  const session = sessionWith(['doc-skill'])
+  const atDesign = extra => ({ ...state({ stage: '设计', ...extra }) })
+
+  const missing = skillBlockers(atDesign(), config, session)
+  assert.ok(missing.some(b => b.includes('artifact evidence')),
+    `an artifact-evidence skill must ask for an artifact; got ${JSON.stringify(missing)}`)
+  assert.ok(!missing.some(b => b.includes('validation command')),
+    'it must NOT ask for a shell command')
+
+  // Record what the stage declares and the blocker clears.
+  const declared = config.artifacts.find(artifact => artifact.stage === '设计')
+  assert.ok(declared !== undefined, 'the standard flow declares an artifact at 设计')
+  const cleared = skillBlockers(atDesign({ artifacts: { [declared.id]: { fields: { approach: 'x' } } } }), config, session)
+  assert.deepEqual(cleared.filter(b => b.includes('doc-skill')), [],
+    'a recorded artifact satisfies artifact evidence')
+})
+
+test('evidence: a judging skill is satisfied by a passing review', () => {
+  const config = withEvidence('review')
+  const session = sessionWith(['code-implement', 'doc-skill'])
+  assert.ok(skillBlockers(state(), config, session).some(b => b.includes('review evidence')),
+    'no review recorded means the review evidence is absent')
+  assert.deepEqual(
+    skillBlockers(state({ review: { outcome: 'pass' } }), config, session).filter(b => b.includes('doc-skill')), [],
+    'a passing review satisfies it')
+})
+
+test('evidence: manual evidence needs an explicit statement, none needs nothing', () => {
+  const manual = withEvidence('manual')
+  const session = sessionWith(['code-implement', 'doc-skill'])
+  assert.ok(skillBlockers(state(), manual, session).some(b => b.includes('manual evidence')),
+    'manual evidence is absent until something is recorded')
+  const recorded = state({ skill_results: { '开发': { 'doc-skill': { evidence: ['reviewed by the lead'] } } } })
+  assert.deepEqual(skillBlockers(recorded, manual, session).filter(b => b.includes('doc-skill')), [],
+    'a recorded statement satisfies manual evidence')
+
+  const none = withEvidence('none')
+  assert.deepEqual(skillBlockers(state(), none, session).filter(b => b.includes('doc-skill')), [],
+    'an advisory skill needs no proof beyond being loaded')
+})
+
+test('evidence: an undeclared extra skill still owes a command receipt', () => {
+  // The historical behaviour must survive: a config that says nothing keeps getting
+  // the command requirement, so existing setups are unaffected.
+  const config = withEvidence(undefined)
+  const session = sessionWith(['code-implement', 'doc-skill'])
+  const blockers = skillBlockers(state(), config, session)
+  assert.ok(blockers.some(b => b.includes('validation command')),
+    `an undeclared skill must still owe a command receipt; got ${JSON.stringify(blockers)}`)
+})

package/.filter-test.mjs

@@ -0,0 +1,93 @@
+/**
+ * Catalog filtering: search and filters must narrow the list without ever hiding
+ * something that is currently in force.
+ *
+ * The panel shows the configuration; a filter that hid a bound skill would make the
+ * panel disagree with the config it is displaying, which is worse than a long list.
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { bindingsForStage, formatResourceRef } from './lib/engine.js'
+import { adoptRecommendation, resolveFlow } from './lib/workflows.js'
+
+/**
+ * The filter the panel applies, lifted so it can be tested without a DOM.
+ *
+ * Mirrors `visibleSkills` in TaskEngineSection: an entry that is bound or shipped
+ * always matches; otherwise the query must appear in its name, description or layer.
+ */
+function visibleSkills(catalog, binding, presetSkills, query, onlySelected) {
+  const boundKeys = new Set((binding?.skills ?? []).map(entry => formatResourceRef(entry.skill)))
+  const presetKeys = new Set(presetSkills.map(entry => formatResourceRef(entry.skill)))
+  const needle = query.trim().toLowerCase()
+  return catalog.filter(entry => {
+    const raw = formatResourceRef(entry.ref)
+    const inForce = boundKeys.has(raw) || presetKeys.has(raw)
+    if (onlySelected && !inForce) return false
+    if (needle === '') return true
+    return inForce
+      || entry.name.toLowerCase().includes(needle)
+      || entry.description.toLowerCase().includes(needle)
+      || entry.sourceLabel.toLowerCase().includes(needle)
+  })
+}
+
+const catalog = [
+  { ref: { source: 'bundled', name: 'code-implement' }, name: 'code-implement', description: '实现', sourceLabel: '内置' },
+  { ref: { source: 'bundled', name: 'code-review' }, name: 'code-review', description: '评审变更', sourceLabel: '内置' },
+  { ref: { source: 'project', name: 'api-audit' }, name: 'api-audit', description: '审计接口契约', sourceLabel: '项目' },
+  { ref: { source: 'user', name: 'doc-writer' }, name: 'doc-writer', description: '写文档', sourceLabel: '用户' },
+]
+const binding = { skills: [{ skill: { source: 'project', name: 'api-audit' }, rules: [] }] }
+
+test('filter: no query shows everything', () => {
+  assert.equal(visibleSkills(catalog, binding, [], '', false).length, 4)
+})
+
+test('filter: the query narrows by name, description and layer', () => {
+  // `api-audit` is bound in this fixture, so it stays visible whatever the query —
+  // that rule is asserted separately, and these expectations include it.
+  const names = (...args) => visibleSkills(...args).map(e => e.name).sort()
+  assert.deepEqual(names(catalog, binding, [], 'writer', false), ['api-audit', 'doc-writer'],
+    'name matches')
+  assert.deepEqual(names(catalog, binding, [], '写文档', false), ['api-audit', 'doc-writer'],
+    'description matches')
+  assert.deepEqual(names(catalog, binding, [], '用户', false), ['api-audit', 'doc-writer'],
+    'the layer label matches, so a user can list one layer')
+  assert.deepEqual(names(catalog, binding, [], '审计', false), ['api-audit'],
+    'a bound skill matching by its own description is shown')
+  assert.deepEqual(names(catalog, binding, [], 'nothing-matches-this', false), ['api-audit'],
+    'a query matching nothing still shows the skill that is in force')
+})
+
+test('filter: a BOUND skill is never hidden by the query', () => {
+  // The panel shows the configuration. A search that hid a skill currently in force
+  // would make the panel disagree with the config it is displaying.
+  const shown = visibleSkills(catalog, binding, [], 'doc', false)
+  assert.ok(shown.some(e => e.name === 'api-audit'),
+    'the bound skill stays visible even though it does not match the query')
+  assert.ok(shown.some(e => e.name === 'doc-writer'), 'and the matching one is shown too')
+})
+
+test('filter: only-selected keeps bound and preset skills, drops the rest', () => {
+  const shown = visibleSkills(catalog, binding, [{ skill: { source: 'bundled', name: 'code-review' } }], '', true)
+  const names = shown.map(e => e.name).sort()
+  assert.deepEqual(names, ['api-audit', 'code-review'],
+    'a bound skill and a preset-shipped one are both in force; the other two are not')
+})
+
+test('filter: only-selected combined with a query still keeps what is in force', () => {
+  const shown = visibleSkills(catalog, binding, [], 'doc', true)
+  assert.ok(shown.some(e => e.name === 'api-audit'),
+    'the filter must not drop a bound skill even when a query is active')
+  assert.ok(!shown.some(e => e.name === 'code-implement'), 'an unbound non-matching skill is dropped')
+})
+
+test('filter: the shipped catalog is small enough that the default view shows it all', () => {
+  // Sanity: the initial view of a fresh project is the shipped set, unfiltered.
+  const adopted = adoptRecommendation('standard')
+  const resolved = resolveFlow('standard', adopted).config
+  const binding = bindingsForStage('开发', resolved)
+  assert.ok(binding !== undefined, 'the adopted config binds 开发')
+  assert.ok((binding.skills ?? []).length > 0)
+})