@godv61/dsh-task-engine 0.24.0 → 0.26.0

package/lib/dev-task.js

@@ -15,7 +15,7 @@ import { homedir } from 'node:os';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { assertAdvance, bindingsForStage, checkFileScope, commitCheckpoint, applyRevision, completionBlockers, formatResourceRef, invalidatedBy, legalTargets, newTask, taskIdFromMessage, unmetGuards, validateCommitMessage, validateWorkflow, verificationBlockers, } from "./engine.js";
+import { assertAdvance, bindingsForStage, checkFileScope, commitCheckpoint, applyRevision, completionBlockers, formatResourceRef, invalidatedBy, legalTargets, resourceBlockers, newTask, taskIdFromMessage, unmetGuards, validateCommitMessage, validateWorkflow, verificationBlockers, } from "./engine.js";
 import { HIGH_RISK_REQUIRED_CAPABILITIES, flowSatisfies, resolveFlow, } from "./workflows.js";
 import { hashConfig, hashText } from "./snapshot.js";
 import { loadedSkills, needsSkillReceipt, obligationStages, skillBlockers } from "./skill-audit.js";
@@ -184,7 +184,15 @@ async function resolveWorkflow(fs, cwd) {
             source: 'invalid',
         };
     }
-    const resolved = resolveFlow(parsed.flow, parsed.stage_bindings !== undefined ? { stage_bindings: parsed.stage_bindings } : undefined);
+    const resolved = resolveFlow(parsed.flow, {
+        flow: parsed.flow,
+        ...(parsed.stage_bindings !== undefined ? { stage_bindings: parsed.stage_bindings } : {}),
+        ...(parsed.skill_profiles !== undefined ? { skill_profiles: parsed.skill_profiles } : {}),
+        ...(parsed.commit !== undefined ? { commit: parsed.commit } : {}),
+        ...(parsed.artifacts !== undefined ? { artifacts: parsed.artifacts } : {}),
+        ...(parsed.review_depth !== undefined ? { review_depth: parsed.review_depth } : {}),
+        ...(parsed.commit_required !== undefined ? { commit_required: parsed.commit_required } : {}),
+    });
     if (!resolved.ok) {
         const standard = standardWorkflow();
         return {
@@ -408,18 +416,18 @@ async function freezeResources(config, fs, cwd) {
     const unreadable = [];
     for (const binding of Object.values(config.stage_bindings ?? {})) {
         for (const entry of binding.skills ?? []) {
-            const skillKey = formatResourceRef(entry.skill);
+            const skillKey = 'skill:' + formatResourceRef(entry.skill);
             if (!seen.has(skillKey)) {
                 const body = await readSkillAt(entry.skill, fs, cwd);
                 if (body === undefined)
                     unreadable.push(skillKey);
                 else {
                     seen.add(skillKey);
-                    resources.push({ ref: entry.skill, hash: hashText(body), content: body });
+                    resources.push({ kind: 'skill', ref: entry.skill, hash: hashText(body), content: body });
                 }
             }
             for (const rule of entry.rules) {
-                const key = formatResourceRef(rule);
+                const key = 'rule:' + formatResourceRef(rule);
                 if (seen.has(key))
                     continue;
                 const body = await readRuleAt(rule.source, rule.name, fs, cwd);
@@ -428,7 +436,7 @@ async function freezeResources(config, fs, cwd) {
                     continue;
                 }
                 seen.add(key);
-                resources.push({ ref: rule, hash: hashText(body), content: body });
+                resources.push({ kind: 'rule', ref: rule, hash: hashText(body), content: body });
             }
         }
     }
@@ -444,7 +452,14 @@ async function freezeResources(config, fs, cwd) {
  * @param fs - sandboxed filesystem for the project-level lookup.
  * @returns the layer that holds this name, or undefined when none does.
  */
-async function resolveLegacyRuleSource(name, fs, cwd) {
+async function resolveLegacyRuleSource(name, fs, cwd, frozen) {
+    // A frozen snapshot answers this without touching the filesystem: the layer a
+    // legacy name resolved to at creation is part of what the task froze, so a
+    // source deleted afterwards cannot change where it resolves.
+    for (const resource of frozen ?? []) {
+        if (resource.kind !== 'skill' && resource.ref.name === name)
+            return resource.ref.source;
+    }
     for (const source of ['bundled', 'project', 'user']) {
         if ((await readRuleAt(source, name, fs, cwd)) !== undefined)
             return source;
@@ -462,18 +477,50 @@ async function resolveLegacyRuleSource(name, fs, cwd) {
  * @param fs - sandboxed filesystem for the project-level lookup.
  * @returns the resolved rules with bodies and sources, plus the refs not found.
  */
-async function resolveRules(refs, fs, cwd) {
+async function resolveRules(refs, fs, cwd, frozen) {
     const resolved = [];
     const missing = [];
+    // A frozen body is the authority for a task that has one. Freezing used to only
+    // ARCHIVE the content: status and the stage disclosure still read the live files,
+    // so editing a rule silently changed what a running task was told to follow —
+    // the exact instability the snapshot exists to prevent.
+    const frozenByRef = new Map();
+    // Pre-0.26 snapshots have no kind. If such a snapshot reused a skill's ref
+    // for a rule, its rule was never frozen; fail closed instead of reading the
+    // skill body as a rule.
+    for (const resource of frozen ?? []) {
+        if (resource.kind === 'rule')
+            frozenByRef.set(formatResourceRef(resource.ref), resource);
+        else if (resource.kind === undefined && !resource.content.startsWith('---')) {
+            frozenByRef.set(formatResourceRef(resource.ref), resource);
+        }
+    }
+    const stale = [];
     for (const ref of refs) {
+        const key = formatResourceRef(ref);
+        const snapshot = frozenByRef.get(key);
+        if (snapshot !== undefined) {
+            resolved.push({ name: ref.name, content: snapshot.content, source: ref.source });
+            // Report when the source no longer matches what was frozen, so drift is
+            // visible instead of looking like the frozen text was simply current.
+            const live = await readRuleAt(ref.source, ref.name, fs, cwd);
+            if (live === undefined)
+                stale.push(key + ' (source deleted)');
+            else if (hashText(live) !== snapshot.hash)
+                stale.push(key + ' (source edited)');
+            continue;
+        }
+        // No snapshot (a pre-freezing task) or this ref was not frozen: read live, and
+        // report a rule that resolves nowhere rather than dropping it, because omitting
+        // it made a deleted file indistinguishable from an unbound one.
         const content = await readRuleAt(ref.source, ref.name, fs, cwd);
         if (content === undefined) {
-            missing.push(formatResourceRef(ref));
+            missing.push(key);
             continue;
         }
         resolved.push({ name: ref.name, content, source: ref.source });
     }
-    return { resolved, missing };
+    return { resolved, missing, stale };
 }
 /**
  * Every rule that applies at a stage, gathered from the skills bound to it.
@@ -487,7 +534,7 @@ async function resolveRules(refs, fs, cwd) {
  * @param fs - sandboxed filesystem for project-level lookups.
  * @returns resolved rules, missing refs, and the unassigned legacy names.
  */
-async function rulesForBinding(binding, fs, cwd) {
+async function rulesForBinding(binding, fs, cwd, frozen) {
     const refs = [];
     // Deduplicated by reference: one rule shared by two skills on the same stage is
     // disclosed once, because it is one constraint being followed.
@@ -501,11 +548,11 @@ async function rulesForBinding(binding, fs, cwd) {
             refs.push(rule);
         }
     }
-    const { resolved, missing } = await resolveRules(refs, fs, cwd);
+    const { resolved, missing, stale } = await resolveRules(refs, fs, cwd, frozen);
     const legacy = binding?.legacy_rules ?? [];
     const legacyRefs = [];
     for (const name of legacy) {
-        const source = await resolveLegacyRuleSource(name, fs, cwd);
+        const source = await resolveLegacyRuleSource(name, fs, cwd, frozen);
         // An unresolvable legacy name is reported through `missing` so it is visible
         // rather than quietly absent.
         if (source === undefined) {
@@ -518,8 +565,27 @@ async function rulesForBinding(binding, fs, cwd) {
         seen.add(key);
         legacyRefs.push({ source, name });
     }
-    const legacyResolved = (await resolveRules(legacyRefs, fs, cwd)).resolved;
-    return { resolved: [...resolved, ...legacyResolved], missing, legacy };
+    const legacyResult = await resolveRules(legacyRefs, fs, cwd, frozen);
+    return {
+        resolved: [...resolved, ...legacyResult.resolved],
+        missing,
+        legacy,
+        stale: [...stale, ...legacyResult.stale],
+    };
+}
+/** Return the task's frozen skill instructions, falling back to live bodies for old tasks. */
+async function skillBodiesForBinding(binding, fs, cwd, frozen) {
+    const result = [];
+    for (const entry of binding?.skills ?? []) {
+        const key = formatResourceRef(entry.skill);
+        const archived = frozen?.find(resource => (resource.kind === 'skill'
+            || (resource.kind === undefined && resource.content.startsWith('---')))
+            && formatResourceRef(resource.ref) === key);
+        const content = archived?.content ?? await readSkillAt(entry.skill, fs, cwd);
+        if (content !== undefined)
+            result.push({ name: entry.skill.name, source: entry.skill.source, content });
+    }
+    return result;
 }
 /**
  * Render a stage's progressive-disclosure payload: skill names to load via the
@@ -530,15 +596,19 @@ async function rulesForBinding(binding, fs, cwd) {
  * @param fs - host filesystem for project-rule resolution.
  * @returns the disclosure text, or an empty string.
  */
-async function renderBindings(stage, workflow, fs, cwd) {
+async function renderBindings(stage, workflow, fs, cwd, frozen) {
     const binding = bindingsForStage(stage, workflow);
     const skills = binding?.skills ?? [];
     if (binding === undefined || (skills.length === 0 && (binding.legacy_rules ?? []).length === 0))
         return '';
-    const { resolved: rules, missing, legacy } = await rulesForBinding(binding, fs, cwd);
+    const { resolved: rules, missing, legacy } = await rulesForBinding(binding, fs, cwd, frozen);
     const skillPart = skills.length > 0
         ? `skills to load: ${skills.map(skill => formatResourceRef(skill.skill)).join(', ')}  (use the skill tool by name)`
         : 'skills to load: none';
+    const frozenSkills = await skillBodiesForBinding(binding, fs, cwd, frozen);
+    const skillInstructions = frozenSkills.length > 0
+        ? `skill instructions for this task (frozen at creation when available; these are authoritative if the live skill changed):\n${frozenSkills.map(skill => `### ${skill.source}:${skill.name}\n${skill.content}`).join('\n\n')}`
+        : '';
     const rulePart = rules.length > 0
         ? `rules in force at this stage (each belongs to the skill shown by the binding):\n${rules.map(r => `### ${r.source}:${r.name}\n${r.content}`).join('\n\n')}`
         : '';
@@ -554,11 +624,18 @@ async function renderBindings(stage, workflow, fs, cwd) {
         ? `UNASSIGNED legacy stage rules: ${legacy.join(', ')} — these belong to the stage, not to any skill. ` +
             'Assign each to the skill that should carry it (or copy the skill and give each copy its own rules) and record it in stage_bindings.'
         : '';
-    const additional = skills.map(skill => skill.skill.name).filter(needsSkillReceipt);
+    // The disclosure names the skills that owe a command receipt, honouring each
+    // binding's declared evidence kind — a document-producing skill owes an
+    // artifact, not a shell command, and saying otherwise would tell the model to
+    // run something irrelevant.
+    const additional = skills
+        .filter(entry => entry.evidence === undefined || entry.evidence === 'command')
+        .map(entry => entry.skill.name)
+        .filter(name => needsSkillReceipt(name));
     const receiptPart = additional.length
         ? `additional skills requiring skill_result command receipts: ${additional.join(', ')}`
         : 'skill_result not required for this stage: core skills use record/verify/review/commit gates';
-    return [skillPart, receiptPart, rulePart, missingPart, legacyPart].filter(Boolean).join('\n');
+    return [skillPart, skillInstructions, receiptPart, rulePart, missingPart, legacyPart].filter(Boolean).join('\n');
 }
 /** Normalize the tool's `items` argument into complete TaskItem records. */
 function normalizeItems(items, previous = []) {
@@ -899,6 +976,9 @@ export function registerDevTask(ctx) {
                 // in-flight task stable: editing a rule the task uses would otherwise change
                 // what the task is doing without the task saying so.
                 const frozen = await freezeResources(resolved.config, fs, cwd);
+                if (frozen.unreadable.length > 0) {
+                    throw new Error(`cannot create task with unreadable bound resources: ${frozen.unreadable.join(', ')}`);
+                }
                 const flow = {
                     flow: resolved.flow,
                     version: resolved.version,
@@ -923,15 +1003,21 @@ export function registerDevTask(ctx) {
                 state.bindings_fingerprint = builtinRulesFingerprint();
                 assertInsideRoot(root, cwd ?? '', taskPath(state.id));
                 await writeTask(fs, state, cwd, await resolveWriteMode(ctx, a, exec));
-                return `created ${state.id} at stage ${state.stage}; legal next: ${legalTargets(state.stage, flow.config).join(', ') || 'none'}\n${await renderBindings(state.stage, flow.config, fs, cwd)}\nBefore advance, load all bound skills. For additional skills, execute their instructions then use skill_result with evidence and command. Terminal bindings must finish before entering the terminal stage.`;
+                return `created ${state.id} at stage ${state.stage}; legal next: ${legalTargets(state.stage, flow.config).join(', ') || 'none'}\n${await renderBindings(state.stage, flow.config, fs, cwd, flow.resources)}\nBefore advance, load all bound skills. Record each skill's declared evidence. Terminal bindings must finish before entering the terminal stage.`;
             }
             if (!a.task_id)
                 throw new Error('task_id is required for this operation');
             const state = await loadTask(fs, a.task_id, cwd);
             const workflow = await workflowFor(state, fs, cwd);
+            if (state.completed !== undefined && a.operation === 'complete') {
+                return `task already completed at ${state.completed.at}`;
+            }
+            if (state.completed !== undefined && a.operation !== 'status' && a.operation !== 'revise') {
+                throw new Error('task is completed; use revise to reopen it before changing task state');
+            }
             if (a.operation === 'status') {
                 const binding = bindingsForStage(state.stage, workflow);
-                const { resolved: rules, missing: missingRules, legacy: legacyRules, } = await rulesForBinding(binding, fs, cwd);
+                const { resolved: rules, missing: missingRules, legacy: legacyRules, stale: staleRules, } = await rulesForBinding(binding, fs, cwd, state.flow?.resources);
                 const missingSkills = skillBlockers(state, workflow, session);
                 const staleEvidence = await evidenceBlockers(fs, state, workflow, cwd);
                 const checkpoint = commitCheckpoint(state, workflow);
@@ -940,19 +1026,31 @@ export function registerDevTask(ctx) {
                 // needs a passing verification and does not have one. Callers act on both.
                 const verification = verificationBlockers(state, workflow);
                 const commitBlockers = [...staleEvidence, ...missingSkills, ...verification];
+                const completionIssues = state.completed === undefined
+                    ? [...completionBlockers(state, workflow), ...missingSkills, ...resourceBlockers(missingRules, state.stage), ...staleEvidence]
+                    : [];
                 return JSON.stringify({
                     id: state.id,
                     stage: state.stage,
                     flow: state.flow !== undefined ? { flow: state.flow.flow, version: state.flow.version } : null,
                     risk_level: state.risk_level,
+                    completed: state.completed ?? null,
+                    completion_blockers: completionIssues,
                     work_size: state.work_size,
                     requirement_confirmed: state.requirement_confirmed,
                     solution_confirmed: state.solution_confirmed,
                     items_done: `${state.items.filter(i => i.status === 'done').length}/${state.items.length}`,
                     items: state.items,
                     skill_obligations: obligationStages(state, workflow).map(stage => {
-                        const skills = (workflow.stage_bindings?.[stage]?.skills ?? []).map(skill => skill.skill.name);
-                        return { stage, skills, command_receipts_required: skills.filter(needsSkillReceipt) };
+                        const bindings = workflow.stage_bindings?.[stage]?.skills ?? [];
+                        const skills = bindings.map(entry => entry.skill.name);
+                        // Only bindings whose evidence is a command owe a command receipt, so a
+                        // document-producing skill is not told to run something irrelevant.
+                        const command_receipts_required = bindings
+                            .filter(entry => entry.evidence === undefined || entry.evidence === 'command')
+                            .map(entry => entry.skill.name)
+                            .filter(name => needsSkillReceipt(name));
+                        return { stage, skills, command_receipts_required };
                     }),
                     skill_blockers: missingSkills,
                     evidence_blockers: staleEvidence,
@@ -963,6 +1061,11 @@ export function registerDevTask(ctx) {
                     // runs under, and this mirrors that list for the current stage.
                     missing_rules: missingRules,
                     rules: rules.map(rule => ({ name: rule.name, source: rule.source })),
+                    // Rules whose SOURCE no longer matches what the task froze. The task keeps
+                    // following the frozen text — that is what freezing is for — and this reports
+                    // the drift, so a rule edited or deleted underneath a running task is visible
+                    // instead of silently authoritative.
+                    stale_source_rules: staleRules,
                     unassigned_legacy_rules: legacyRules,
                     skill_results: state.skill_results ?? {},
                     commits: state.commits,
@@ -980,7 +1083,12 @@ export function registerDevTask(ctx) {
                         : checkpoint,
                     bindings: {
                         skills: binding?.skills ?? [],
-                        rules: rules.map(r => ({ name: r.name, content: r.content })),
+                        skill_contents: await skillBodiesForBinding(binding, fs, cwd, state.flow?.resources),
+                        // The layer is disclosed with each rule, because two same-named rules in
+                        // different layers are distinct resources and the caller needs to know
+                        // which one is actually in force. Reporting only the name made them
+                        // indistinguishable in exactly the case where the distinction matters.
+                        rules: rules.map(r => ({ name: r.name, source: r.source, content: r.content })),
                     },
                     bindings_drift: state.bindings_fingerprint !== undefined && state.bindings_fingerprint !== builtinRulesFingerprint()
                         ? 'bundled rules changed since this task froze — the frozen fingerprint no longer matches the shipped rules'
@@ -1043,7 +1151,13 @@ export function registerDevTask(ctx) {
                 // leaving a checkpoint" rule fires on the way OUT of a stage and a
                 // terminal stage has no way out.
                 await assertFreshEvidence(fs, state, workflow, cwd);
-                const blockers = completionBlockers(state, workflow);
+                const missingSkills = skillBlockers(state, workflow, session);
+                const unresolvedRules = (await rulesForBinding(bindingsForStage(state.stage, workflow), fs, cwd, state.flow?.resources)).missing;
+                const blockers = [
+                    ...completionBlockers(state, workflow),
+                    ...missingSkills,
+                    ...resourceBlockers(unresolvedRules, state.stage),
+                ];
                 if (blockers.length > 0)
                     throw new Error(`cannot complete: ${blockers.join('; ')}`);
                 const hash = state.commits.find(commit => commit.hash !== undefined)?.hash;
@@ -1150,6 +1264,14 @@ export function registerDevTask(ctx) {
                     const missingSkills = skillBlockers(state, workflow, session);
                     if (missingSkills.length)
                         throw new Error(missingSkills.join('; '));
+                    // A stage whose rules cannot be resolved must not be passable. This was
+                    // reported in status and never enforced, so deleting a bound rule still let the
+                    // task advance — the stage ran without the constraints it was configured with
+                    // while the record looked fine.
+                    const unresolvedRules = (await rulesForBinding(bindingsForStage(state.stage, workflow), fs, cwd, state.flow?.resources)).missing;
+                    const resourceIssues = resourceBlockers(unresolvedRules, state.stage);
+                    if (resourceIssues.length)
+                        throw new Error(resourceIssues.join('; '));
                     let result = assertAdvance(state, target, workflow);
                     if (!result.ok) {
                         const unmet = unmetGuards(state, target, workflow);
@@ -1163,9 +1285,9 @@ export function registerDevTask(ctx) {
                     if (!result.ok)
                         throw new Error(result.errors.join('; '));
                     state.stage = target;
-                    const disclosure = await renderBindings(state.stage, workflow, fs, cwd);
+                    const disclosure = await renderBindings(state.stage, workflow, fs, cwd, state.flow?.resources);
                     const terminalObligations = obligationStages(state, workflow).filter(stage => stage !== state.stage);
-                    const terminalDisclosure = await Promise.all(terminalObligations.map(async (stage) => `Before entering ${stage}, execute its bindings now:\n${await renderBindings(stage, workflow, fs, cwd)}`));
+                    const terminalDisclosure = await Promise.all(terminalObligations.map(async (stage) => `Before entering ${stage}, execute its bindings now:\n${await renderBindings(stage, workflow, fs, cwd, state.flow?.resources)}`));
                     note = [`advanced to ${state.stage}`, disclosure, ...terminalDisclosure].filter(Boolean).join('\n');
                     break;
                 }
@@ -1243,11 +1365,31 @@ export function registerDevTask(ctx) {
                 }
                 case 'skill_result': {
                     const stage = a.target_stage ?? state.stage;
-                    if (!obligationStages(state, workflow).includes(stage) || !(workflow.stage_bindings?.[stage]?.skills ?? []).some(entry => entry.skill.name === a.skill_name))
+                    const entry = (workflow.stage_bindings?.[stage]?.skills ?? []).find(binding => binding.skill.name === a.skill_name);
+                    if (!obligationStages(state, workflow).includes(stage) || !entry)
                         throw new Error('skill_result requires a skill bound to this stage or its upcoming terminal stage');
                     const loadCall = loadedSkills(session).get(a.skill_name);
                     if (!loadCall)
                         throw new Error(`load skill "${a.skill_name}" successfully before recording execution`);
+                    if (entry.evidence === 'manual') {
+                        if (!a.evidence?.length || a.evidence.some(value => !value.trim()))
+                            throw new Error('manual skill_result requires non-empty evidence');
+                        const approval = ctx.get('approval');
+                        if (approval === undefined || exec.agent === undefined)
+                            throw new Error('manual skill_result requires the human approval service');
+                        const outcome = await approval.request({ agent: exec.agent, toolName: 'dev_task', callId: exec.callId,
+                            reason: `请确认技能 ${a.skill_name} 在 ${stage} 的人工结果：${a.evidence.join('；')}`, signal: exec.signal });
+                        if (outcome !== 'allowed-once')
+                            throw new Error(`manual skill_result was not approved (${outcome})`);
+                        state.skill_results ??= {};
+                        state.skill_results[stage] ??= {};
+                        state.skill_results[stage][a.skill_name] = { session_id: session?.id ?? '', load_call_id: loadCall, evidence: a.evidence, approved: true };
+                        note = JSON.stringify({ skill: a.skill_name, stage, approved: true }, null, 2);
+                        break;
+                    }
+                    if (entry.evidence === 'artifact' || entry.evidence === 'review' || entry.evidence === 'none') {
+                        throw new Error(`${entry.evidence} skill evidence is recorded by its node operation; skill_result is only for command or manual evidence`);
+                    }
                     if (!a.command?.trim() || !a.evidence?.length || a.evidence.some(value => !value.trim()))
                         throw new Error('skill_result requires a real validation command and non-empty evidence describing executed scenarios and results');
                     approvedWriteMode = await resolveWriteMode(ctx, a, exec);