@godv61/dsh-task-engine 0.23.8 → 0.24.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, legalTargets, newTask, taskIdFromMessage, unmetGuards, validateCommitMessage, validateWorkflow, } from "./engine.js";
+import { assertAdvance, bindingsForStage, checkFileScope, commitCheckpoint, applyRevision, completionBlockers, formatResourceRef, invalidatedBy, legalTargets, 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";
@@ -342,36 +342,184 @@ function builtinRulesFingerprint() {
         .join('\n');
     return hashText(contents);
 }
+/** Read one rule body from a specific layer, so a reference decides where to look. */
+async function readRuleAt(source, name, fs, cwd) {
+    const safe = sanitize(name);
+    if (safe === '')
+        return undefined;
+    switch (source) {
+        case 'bundled':
+            return readAbsRule(fileURLToPath(new URL(`../rules/${safe}.md`, import.meta.url)));
+        case 'project':
+            return await readText(fs, `.dsh/rules/${safe}.md`, cwd);
+        case 'user':
+            return readAbsRule(join(dshHome(), 'rules', `${safe}.md`));
+    }
+}
+/** Bundled skill directory, the only layer whose bodies this process can read without the host registry. */
+const BUNDLED_SKILLS_DIR = fileURLToPath(new URL('../skills/', import.meta.url));
 /**
- * Resolve rule contents by name: bundled first, then user home, then project.
- * Bundled (core) rules win over user and project files of the same name, so a
- * project cannot shadow a shipped rule like `security-redlines` with a weaker
- * local copy; local additions use distinct names instead.
- * @param names - rule names from the current stage binding.
+ * Read one skill body from a layer this process can reach.
+ *
+ * Project-level skills live under the workspace and are readable through the
+ * sandboxed fs; user-level ones sit under the harness home. A skill the host
+ * registry resolves but this process cannot read yields undefined, which is
+ * reported as unfreezable rather than silently omitted — the task must not claim
+ * to have frozen something it did not read.
+ * @param ref - the skill reference from a stage binding.
  * @param fs - sandboxed filesystem for the project-level lookup.
- * @returns the rules that resolved, in name order, with their bodies.
+ * @returns the SKILL.md body, or undefined when it cannot be read here.
  */
-async function resolveRules(names, fs, cwd) {
-    const result = [];
-    for (const rawName of names) {
-        const name = sanitize(rawName);
-        if (name === '')
-            continue;
-        const bundled = readAbsRule(fileURLToPath(new URL(`../rules/${name}.md`, import.meta.url)));
-        if (bundled !== undefined) {
-            result.push({ name: rawName, content: bundled });
+async function readSkillAt(ref, fs, cwd) {
+    const safe = sanitize(ref.name);
+    if (safe === '')
+        return undefined;
+    const read = (path) => {
+        try {
+            return readFileSync(path, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    };
+    switch (ref.source) {
+        case 'bundled':
+            return read(join(BUNDLED_SKILLS_DIR, safe, 'SKILL.md'));
+        case 'project':
+            return await readText(fs, '.dsh/skills/' + safe + '/SKILL.md', cwd);
+        case 'user':
+            return read(join(dshHome(), 'skills', safe, 'SKILL.md'));
+    }
+}
+/**
+ * Freeze every skill and rule body the config resolves to.
+ *
+ * Names alone cannot keep an in-flight task stable: editing a rule that a running
+ * task uses would silently change what that task is doing. Each resolved body is
+ * copied with its content hash, so a deleted or edited source cannot change a
+ * running task, and identical bodies are stored once per hash.
+ * @param config - the frozen workflow config.
+ * @param fs - sandboxed filesystem for project-level lookups.
+ * @returns the frozen resources plus the refs that could not be read.
+ */
+async function freezeResources(config, fs, cwd) {
+    const seen = new Set();
+    const resources = [];
+    const unreadable = [];
+    for (const binding of Object.values(config.stage_bindings ?? {})) {
+        for (const entry of binding.skills ?? []) {
+            const skillKey = 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 });
+                }
+            }
+            for (const rule of entry.rules) {
+                const key = formatResourceRef(rule);
+                if (seen.has(key))
+                    continue;
+                const body = await readRuleAt(rule.source, rule.name, fs, cwd);
+                if (body === undefined) {
+                    unreadable.push(key);
+                    continue;
+                }
+                seen.add(key);
+                resources.push({ ref: rule, hash: hashText(body), content: body });
+            }
+        }
+    }
+    return { resources, unreadable };
+}
+/**
+ * Resolve a bare legacy rule name to the layer that precedence selects.
+ *
+ * Precedence, unchanged from before: bundled wins over project, which wins over
+ * user. A project cannot shadow a shipped rule like `security-redlines` with a
+ * weaker local copy; local additions use distinct names instead.
+ * @param name - the bare rule name from a legacy config.
+ * @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) {
+    for (const source of ['bundled', 'project', 'user']) {
+        if ((await readRuleAt(source, name, fs, cwd)) !== undefined)
+            return source;
+    }
+    return undefined;
+}
+/**
+ * Resolve rule references to their bodies.
+ *
+ * Each reference names its own layer, so the lookup is exact: no precedence walk
+ * is involved and two same-named rules in different layers are distinct
+ * resources. A reference that resolves nowhere is reported rather than dropped —
+ * omitting it made a deleted file indistinguishable from an unbound one.
+ * @param refs - rule references, each with its source layer.
+ * @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) {
+    const resolved = [];
+    const missing = [];
+    for (const ref of refs) {
+        const content = await readRuleAt(ref.source, ref.name, fs, cwd);
+        if (content === undefined) {
+            missing.push(formatResourceRef(ref));
             continue;
         }
-        const project = await readText(fs, `.dsh/rules/${name}.md`, cwd);
-        if (project !== undefined) {
-            result.push({ name: rawName, content: project });
+        resolved.push({ name: ref.name, content, source: ref.source });
+    }
+    return { resolved, missing };
+}
+/**
+ * Every rule that applies at a stage, gathered from the skills bound to it.
+ *
+ * A stage has no rule list of its own: the rules in force are the ones its skills
+ * carry. Both shapes are collected here so a migrated config is not silently
+ * weaker than the one it came from — `legacy_rules` still apply until a human
+ * assigns them — and the two groups stay distinguishable in the return value so
+ * the caller can say which rules still need an owner.
+ * @param binding - the stage's binding, if any.
+ * @param fs - sandboxed filesystem for project-level lookups.
+ * @returns resolved rules, missing refs, and the unassigned legacy names.
+ */
+async function rulesForBinding(binding, fs, cwd) {
+    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.
+    const seen = new Set();
+    for (const skill of binding?.skills ?? []) {
+        for (const rule of skill.rules) {
+            const key = formatResourceRef(rule);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            refs.push(rule);
+        }
+    }
+    const { resolved, missing } = await resolveRules(refs, fs, cwd);
+    const legacy = binding?.legacy_rules ?? [];
+    const legacyRefs = [];
+    for (const name of legacy) {
+        const source = await resolveLegacyRuleSource(name, fs, cwd);
+        // An unresolvable legacy name is reported through `missing` so it is visible
+        // rather than quietly absent.
+        if (source === undefined) {
+            missing.push(name);
             continue;
         }
-        const user = readAbsRule(join(dshHome(), 'rules', `${name}.md`));
-        if (user !== undefined)
-            result.push({ name: rawName, content: user });
+        const key = formatResourceRef({ source, name });
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        legacyRefs.push({ source, name });
     }
-    return result;
+    const legacyResolved = (await resolveRules(legacyRefs, fs, cwd)).resolved;
+    return { resolved: [...resolved, ...legacyResolved], missing, legacy };
 }
 /**
  * Render a stage's progressive-disclosure payload: skill names to load via the
@@ -385,21 +533,32 @@ async function resolveRules(names, fs, cwd) {
 async function renderBindings(stage, workflow, fs, cwd) {
     const binding = bindingsForStage(stage, workflow);
     const skills = binding?.skills ?? [];
-    const ruleNames = binding?.rules ?? [];
-    if (binding === undefined || (skills.length === 0 && ruleNames.length === 0))
+    if (binding === undefined || (skills.length === 0 && (binding.legacy_rules ?? []).length === 0))
         return '';
-    const rules = await resolveRules(ruleNames, fs, cwd);
+    const { resolved: rules, missing, legacy } = await rulesForBinding(binding, fs, cwd);
     const skillPart = skills.length > 0
-        ? `skills to load: ${skills.join(', ')}  (use the skill tool by name)`
+        ? `skills to load: ${skills.map(skill => formatResourceRef(skill.skill)).join(', ')}  (use the skill tool by name)`
         : 'skills to load: none';
     const rulePart = rules.length > 0
-        ? `rules for this stage:\n${rules.map(r => `### ${r.name}\n${r.content}`).join('\n\n')}`
+        ? `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')}`
+        : '';
+    // A bound rule that resolves nowhere is stated explicitly. Silently dropping it
+    // left the stage looking as if the constraint had never been configured.
+    const missingPart = missing.length > 0
+        ? `rules in force at this stage but NOT FOUND in their declared layer: ${missing.join(', ')}`
         : '';
-    const additional = skills.filter(needsSkillReceipt);
+    // Legacy stage-level rules are disclosed (so nothing is lost) but named as
+    // unassigned, because a stage-level list never recorded which skill they were
+    // meant for and guessing would invent an answer the config did not contain.
+    const legacyPart = legacy.length > 0
+        ? `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);
     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].filter(Boolean).join('\n');
+    return [skillPart, receiptPart, rulePart, missingPart, legacyPart].filter(Boolean).join('\n');
 }
 /** Normalize the tool's `items` argument into complete TaskItem records. */
 function normalizeItems(items, previous = []) {
@@ -447,8 +606,21 @@ async function evidenceBlockers(fs, state, workflow, cwd) {
         return [];
     const blockers = [];
     const current = await scopeFingerprint(fs, state, cwd);
-    if (state.verification.passed && state.verification.receipt?.scope_hash !== current) {
-        blockers.push('verification is missing or stale after file/scope changes; rerun verify with a real command');
+    // Staleness is judged on the RECORDED verification, not only on a passing one.
+    // Gating this on `passed` meant a re-verification that FAILED removed its own
+    // receipt from consideration, so the failure produced no blocker at all —
+    // failing verification was strictly weaker than never verifying. A receipt that
+    // exists but no longer matches the current tree, or a verification that is not
+    // passing while the flow requires it, both belong here.
+    const receipt = state.verification.receipt;
+    if (receipt !== undefined && receipt.scope_hash !== current) {
+        blockers.push('verification is stale after file/scope changes; rerun verify with a real command');
+    }
+    else if (!state.verification.passed && verificationBlockers(state, workflow).length > 0) {
+        // Only where the flow actually holds a verification requirement: a task that
+        // has not reached a verification gate yet has nothing to re-verify, and
+        // reporting it there would block the flow from starting at all.
+        blockers.push('verification is not passing; rerun verify with a real command');
     }
     for (const stage of obligationStages(state, workflow)) {
         for (const [name, result] of Object.entries(state.skill_results?.[stage] ?? {})) {
@@ -510,13 +682,15 @@ export async function approveAdvance(ctx, state, target, workflow, confirmations
         state.solution_confirmed = true;
     return assertAdvance(state, target, workflow);
 }
-const OPERATIONS = ['status', 'create', 'record', 'items', 'scope', 'dispatch', 'review_item', 'advance', 'verify', 'review', 'commit', 'config', 'install_hook', 'verify_hook', 'init', 'set_risk', 'skill_result'];
+const OPERATIONS = ['status', 'create', 'record', 'items', 'scope', 'dispatch', 'review_item', 'advance', 'verify', 'review', 'commit', 'complete', 'revise', 'config', 'install_hook', 'verify_hook', 'init', 'set_risk', 'skill_result'];
 const TOOL_DESCRIPTION = 'Own the engineering delivery workflow as hard state. Read or create the task record, record a ' +
     'stage artifact, record each implementation item\'s subagent dispatch and two-stage (spec + quality) ' +
-    'review audit, advance one stage (rejected unless every configured guard already holds, including ' +
+    'review audit (the flow decides how many verdicts per item), advance one stage (rejected unless every configured guard already holds, including ' +
     'the stage artifacts; a requirement/solution confirmation guard asks a human to approve instead of ' +
     'being satisfied by the model), record verification or review, and gate a commit on ' +
-    'stage/scope/message. The init operation manages the protected AGENTS.md in three phases ' +
+    'stage/scope/message, and mark the task complete only once its configured finish conditions ' +
+    'hold — reaching the last stage is not itself completion. The init operation manages the ' +
+    'protected AGENTS.md in three phases ' +
     '(inspect → propose → apply; overwriting an existing file requires human approval) because DSH ' +
     'injects that file into every session. The tool refuses illegal moves ' +
     'instead of degrading — treat a rejection as a fact to fix, not a prompt to retry another way.';
@@ -556,7 +730,7 @@ export function registerDevTask(ctx) {
             spec_outcome: { type: 'string', enum: ['pass', 'fail'], description: 'Specification-conformance verdict (review_item).' },
             quality_outcome: { type: 'string', enum: ['pass', 'fail'], description: 'Code-quality verdict (review_item).' },
             notes: { type: 'array', items: { type: 'string' }, description: 'Findings or defects (review_item).' },
-            target_stage: { type: 'string', description: 'Stage to advance to, or current/upcoming terminal skill binding stage for skill_result.' },
+            target_stage: { type: 'string', description: 'Stage to advance to (advance), a bound stage for skill_result, or the stage to return to (revise). For revise it must be the stage the changed decision belongs to. Current/upcoming terminal skill binding stage for skill_result.' },
             command: { type: 'string', description: 'Real acceptance command for verify/skill_result. New tasks require command receipts. Propagate failures when composing shell commands.' },
             passed: { type: 'boolean', description: 'Legacy tasks only: verification claim when no command can be resolved. New tasks require real command receipts.' },
             evidence: { type: 'array', items: { type: 'string' }, description: 'Supplementary verification evidence (verify).' },
@@ -573,6 +747,8 @@ export function registerDevTask(ctx) {
                 description: 'Repo-relative paths in scope (create/scope) or being committed (commit).',
             },
             message: { type: 'string', description: 'Commit summary to validate (commit).' },
+            revision_kind: { type: 'string', enum: ['requirement', 'solution', 'defect'], description: 'Why the task is going back (revise). Decides which conclusions are invalidated: requirement clears its confirmation and everything downstream; solution keeps the requirement agreed; defect clears only the evidence about the old implementation.' },
+            revision_reason: { type: 'string', description: 'What changed, in the author\'s words (revise).' },
             hash: { type: 'string', description: 'Commit hash to record after the git commit (commit).' },
             content: { type: 'string', description: 'Full AGENTS.md body (init propose/apply). Inspect the existing file first via init phase=inspect.' },
             overwrite: { type: 'boolean', description: 'Allow replacing an existing AGENTS.md (init apply); triggers human approval.' },
@@ -719,11 +895,16 @@ export function registerDevTask(ctx) {
                     throw new Error(`high_risk task cannot run on flow "${resolved.flow}" — it lacks the required capabilities ` +
                         `(${HIGH_RISK_REQUIRED_CAPABILITIES.join(', ')}). Use the standard flow or lower the task risk.`);
                 }
+                // Freeze the resolved skill and rule bodies now. A name alone cannot keep an
+                // 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);
                 const flow = {
                     flow: resolved.flow,
                     version: resolved.version,
                     config: resolved.config,
                     hash: hashConfig(resolved.config),
+                    resources: frozen.resources,
                 };
                 const root = await detectRoot(projectProbe(fs), cwd ?? '');
                 const state = newTask({
@@ -750,11 +931,15 @@ export function registerDevTask(ctx) {
             const workflow = await workflowFor(state, fs, cwd);
             if (a.operation === 'status') {
                 const binding = bindingsForStage(state.stage, workflow);
-                const rules = await resolveRules(binding?.rules ?? [], fs, cwd);
+                const { resolved: rules, missing: missingRules, legacy: legacyRules, } = await rulesForBinding(binding, fs, cwd);
                 const missingSkills = skillBlockers(state, workflow, session);
                 const staleEvidence = await evidenceBlockers(fs, state, workflow, cwd);
                 const checkpoint = commitCheckpoint(state, workflow);
-                const commitBlockers = [...staleEvidence, ...missingSkills];
+                // The flow's verification requirement is reported separately from staleness:
+                // one says the receipt no longer matches the tree, the other says the flow
+                // needs a passing verification and does not have one. Callers act on both.
+                const verification = verificationBlockers(state, workflow);
+                const commitBlockers = [...staleEvidence, ...missingSkills, ...verification];
                 return JSON.stringify({
                     id: state.id,
                     stage: state.stage,
@@ -765,12 +950,20 @@ export function registerDevTask(ctx) {
                     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 => ({
-                        stage, skills: workflow.stage_bindings?.[stage]?.skills ?? [],
-                        command_receipts_required: (workflow.stage_bindings?.[stage]?.skills ?? []).filter(needsSkillReceipt),
-                    })),
+                    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) };
+                    }),
                     skill_blockers: missingSkills,
                     evidence_blockers: staleEvidence,
+                    verification_blockers: verification,
+                    // Rules in force here, each named with the layer it came from, plus the
+                    // ones that could not be found and the legacy stage-level names still
+                    // awaiting an owner. A skill's own list is the complete answer to what it
+                    // runs under, and this mirrors that list for the current stage.
+                    missing_rules: missingRules,
+                    rules: rules.map(rule => ({ name: rule.name, source: rule.source })),
+                    unassigned_legacy_rules: legacyRules,
                     skill_results: state.skill_results ?? {},
                     commits: state.commits,
                     verification: state.verification,
@@ -843,6 +1036,55 @@ export function registerDevTask(ctx) {
                     return `commit recorded (${checkpoint.label ?? ''}): ${a.hash}; use status to inspect remaining gates, then advance`;
                 return `commit approved (${checkpoint.label ?? ''}) — git add ${(a.files ?? []).join(' ')}; git commit -m "${a.message ?? ''}"`;
             }
+            if (a.operation === 'complete') {
+                // Completion is recorded, not inferred from standing on the last stage.
+                // A flow whose final stage is also its commit checkpoint used to reach
+                // that stage with no delivery record at all, because the "commit before
+                // 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);
+                if (blockers.length > 0)
+                    throw new Error(`cannot complete: ${blockers.join('; ')}`);
+                const hash = state.commits.find(commit => commit.hash !== undefined)?.hash;
+                state.completed = hash === undefined
+                    ? { at: new Date().toISOString() }
+                    : { at: new Date().toISOString(), commit_hash: hash };
+                await writeTask(fs, state, cwd, await resolveWriteMode(ctx, a, exec));
+                return hash === undefined
+                    ? `task completed at "${state.stage}"; the record stays readable for audit`
+                    : `task completed at "${state.stage}" (commit ${hash}); the record stays readable for audit`;
+            }
+            if (a.operation === 'revise') {
+                // The graph has only forward edges, but the work does not: a requirement can
+                // change after implementation started. Before this, going back meant hand-
+                // editing the record, which left every downstream conclusion looking intact
+                // even though it described a superseded tree.
+                const kind = a.revision_kind;
+                if (kind !== 'requirement' && kind !== 'solution' && kind !== 'defect') {
+                    throw new Error('revise requires revision_kind: one of requirement, solution, defect');
+                }
+                if (!a.revision_reason?.trim())
+                    throw new Error('revise requires revision_reason describing what changed');
+                const target = a.target_stage;
+                if (target === undefined || !workflow.stages.includes(target)) {
+                    throw new Error('revise requires target_stage naming a stage of this flow: ' + workflow.stages.join(', '));
+                }
+                if (target === state.stage)
+                    throw new Error('revise target_stage is the current stage; nothing to return to');
+                // Which stages are reachable backwards is a property of the flow, not of the
+                // tool: any earlier stage is a legal place to resume from.
+                if (workflow.stages.indexOf(target) > workflow.stages.indexOf(state.stage)) {
+                    throw new Error('revise goes backwards only; "' + target + '" comes after "' + state.stage + '" in this flow');
+                }
+                const outcome = applyRevision(state, {
+                    kind, reason: a.revision_reason.trim(), to: target, from: state.stage,
+                    at: new Date().toISOString(), invalidated: invalidatedBy(kind),
+                });
+                await writeTask(fs, state, cwd, await resolveWriteMode(ctx, a, exec));
+                return 'revised (' + kind + ') back to "' + outcome.stage + '"; invalidated: ' + outcome.invalidated.join(', ')
+                    + '. Re-establish these before advancing again; the history is kept in the task record.';
+            }
             let note;
             let approvedWriteMode;
             switch (a.operation) {
@@ -1001,7 +1243,7 @@ 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?.includes(a.skill_name ?? ''))
+                    if (!obligationStages(state, workflow).includes(stage) || !(workflow.stage_bindings?.[stage]?.skills ?? []).some(entry => entry.skill.name === a.skill_name))
                         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)