@deniscodp/skills 0.0.0-stage → 1.0.0

package/skills/denisco-workflow-benchmark/scripts/workflow.mjs

@@ -0,0 +1,334 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { hash, inside, loadRun, readJSON, rejectSymlinkPath, safeId, writeNew, writeJSON } from './io.mjs';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { collect, summarize, usageState } from './runs.mjs';
+import { checkStatePrompt, updateStatePrompt } from './state-prompt.mjs';
+
+const canonical = file => process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file);
+const samePath = (a, b) => canonical(a) === canonical(b);
+export const workflowPath = handoff => `${path.resolve(handoff)}.workflow.json`;
+const contractHash = run => hash(JSON.stringify(run.criteria.map(c => ({ id: c.id, expectation: c.expectation, required: c.required !== false })).sort((a, b) => a.id.localeCompare(b.id))));
+function realFile(file) {
+  rejectSymlinkPath(file);
+  if (!fs.statSync(file).isFile()) throw new Error(`Expected a file: ${file}`);
+  return file;
+}
+function ids(values, label, allowEmpty = false) {
+  if (!Array.isArray(values) || (!allowEmpty && !values.length) || new Set(values).size !== values.length) throw new Error(`Invalid ${label}: expected unique IDs`);
+  values.forEach(safeId);
+}
+function validate(data, handoff, { documents = false } = {}) {
+  if (data.schemaVersion !== 1) throw new Error('Unsupported workflow format');
+  safeId(data.taskId);
+  const base = path.dirname(workflowPath(handoff)), paths = {};
+  for (const key of ['handoff', 'plan', 'state']) {
+    if (typeof data[key] !== 'string' || !data[key].trim()) throw new Error(`Missing workflow ${key}`);
+    paths[key] = path.resolve(base, data[key]);
+    if (documents || key === 'handoff') realFile(paths[key]);
+  }
+  if (!samePath(paths.handoff, handoff)) throw new Error('Workflow refers to a different handoff');
+  if (new Set(Object.values(paths).map(canonical)).size !== 3) throw new Error('Handoff, plan and state must be distinct files');
+  if (!['enabled', 'disabled', 'unknown'].includes(data.measurement?.status)) throw new Error('Invalid measurement status');
+  if (data.measurement.status !== 'enabled' && Object.keys(data.measurement).some(k => k !== 'status')) throw new Error('Inactive measurement must not retain an ambiguous run binding');
+  if (!Array.isArray(data.blocks)) throw new Error('Missing block map');
+  ids(data.blocks.map(b => b.id), 'blocks', true);
+  for (const block of data.blocks) {
+    ids(block.points, `${block.id} points`);
+    ids(block.criteria, `${block.id} criteria`);
+    ids(block.dependsOn, `${block.id} dependencies`, true);
+    if (block.dependsOn.some(id => !data.blocks.some(b => b.id === id))) throw new Error(`Unknown dependency in ${block.id}`);
+  }
+  const visiting = new Set(), visited = new Set();
+  function visit(id) {
+    if (visiting.has(id)) throw new Error('Cyclic block dependencies');
+    if (visited.has(id)) return;
+    visiting.add(id);
+    data.blocks.find(b => b.id === id).dependsOn.forEach(visit);
+    visiting.delete(id); visited.add(id);
+  }
+  data.blocks.forEach(b => visit(b.id));
+  if (data.visualChecks !== undefined) {
+    if (!Array.isArray(data.visualChecks) || new Set(data.visualChecks.map(check => check.id)).size !== data.visualChecks.length) throw new Error('Invalid visual check map');
+    for (const check of data.visualChecks) {
+      safeId(check.id); safeId(check.block); ids(check.criteria, `${check.id} criteria`);
+      if (!data.blocks.some(block => block.id === check.block)) throw new Error(`Unknown visual check block: ${check.block}`);
+      if (check.criteria.some(criterion => !data.blocks.find(block => block.id === check.block)?.criteria.includes(criterion))) throw new Error(`Visual check criterion is outside its block: ${check.id}`);
+      if (!['principal', 'subagent'].includes(check.executor)) throw new Error(`Invalid visual check executor: ${check.id}`);
+    }
+  }
+  return paths;
+}
+function checkRun(data, run, paths, { complete = false } = {}) {
+  // A task can have a project ID distinct from the benchmark ID; the explicit binding carries both.
+  inside(run.project, path.relative(run.project, paths.handoff));
+  const assigned = new Set(data.blocks.flatMap(b => b.criteria));
+  for (const id of assigned) if (!run.criteria.some(c => c.id === id)) throw new Error(`Unknown mapped criterion: ${id}`);
+  if (complete) {
+    if (!data.blocks.length) throw new Error('Block map is not ready');
+    const missing = run.criteria.filter(c => c.required !== false && !assigned.has(c.id));
+    if (missing.length) throw new Error(`Required criteria omitted from block map: ${missing.map(c => c.id).join(', ')}`);
+  }
+}
+
+export function bind({ handoff, run: file, task, plan, state }) {
+  handoff = realFile(path.resolve(handoff));
+  file = realFile(path.resolve(file));
+  const run = loadRun(file), target = workflowPath(handoff), base = path.dirname(target);
+  rejectSymlinkPath(target);
+  const exists = fs.existsSync(target);
+  const data = exists ? readJSON(target) : {
+    schemaVersion: 1, taskId: task ?? run.task, handoff: path.basename(handoff),
+    plan: path.relative(base, plan ? path.resolve(plan) : path.join(base, 'PLAN.md')),
+    state: path.relative(base, state ? path.resolve(state) : path.join(base, 'STATE.md')),
+    measurement: { status: 'unknown' }, blocks: []
+  };
+  const original = JSON.stringify(data);
+  const paths = validate(data, handoff);
+  if ((task && task !== data.taskId) || (plan && !samePath(plan, paths.plan)) || (state && !samePath(state, paths.state))) throw new Error('Existing workflow paths/task conflict; review without overwriting');
+  const measurement = { status: 'enabled', run: file, runId: run.id, taskId: run.task, criteriaHash: contractHash(run) };
+  if (data.measurement.status === 'disabled') throw new Error('Measurement explicitly disabled; review the workflow before binding');
+  if (data.measurement.status === 'enabled' && !sameBinding(data.measurement, measurement)) throw new Error('Conflicting run binding or changed criteria; no files changed');
+  checkRun(data, run, paths);
+  const assigned = new Set(data.blocks.flatMap(b => b.criteria));
+  const mapReady = data.blocks.length > 0 && run.criteria.filter(c => c.required !== false).every(c => assigned.has(c.id));
+  if (data.measurement.status === 'enabled') return { workflow: target, changed: false, mapReady };
+  data.measurement = measurement;
+  // The sidecar is the only write target. Existing documents and run history are not rewritten.
+  if (exists) {
+    const lock = `${target}.lock`, fd = fs.openSync(lock, 'wx');
+    try {
+      if (JSON.stringify(readJSON(target)) !== original) throw new Error('Workflow changed during bind; retry after review');
+      // writeJSON is atomic; use it only after rechecking the existing sidecar under its lock.
+      writeJSON(target, data);
+    } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
+  } else writeNew(target, `${JSON.stringify(data, null, 2)}\n`);
+  return { workflow: target, changed: true, mapReady };
+}
+
+function sameBinding(a, b) {
+  return typeof a.run === 'string' && path.isAbsolute(a.run) && samePath(a.run, b.run)
+    && a.runId === b.runId && a.taskId === b.taskId && a.criteriaHash === b.criteriaHash;
+}
+export function readWorkflow(handoff, { draft = false } = {}) {
+  const file = realFile(workflowPath(handoff)), data = readJSON(file);
+  const paths = validate(data, path.resolve(handoff), { documents: !draft });
+  let run = null;
+  if (data.measurement.status === 'enabled') {
+    const binding = data.measurement;
+    if (typeof binding.run !== 'string' || !path.isAbsolute(binding.run)) throw new Error('Measurement run must be an absolute path');
+    run = loadRun(realFile(binding.run));
+    if (!sameBinding(binding, { run: binding.run, runId: run.id, taskId: run.task, criteriaHash: contractHash(run) })) throw new Error('Run identity or criteria changed since binding');
+    checkRun(data, run, paths, { complete: !draft });
+  }
+  return { file, data, paths, run };
+}
+function blockQuality(run, block) {
+  if (!run) return null;
+  const criteria = run.criteria.filter(c => block.criteria.includes(c.id));
+  if (!criteria.some(c => c.required !== false)) return { quality: 'unverified', passed: 0, required: 0 };
+  return summarize({ ...run, criteria });
+}
+export function checkpoint({ handoff, block: id, implementation, sessionKey, sessionState = 'unknown', claim, nextBlock }) {
+  if (!['complete', 'in-progress', 'not-started'].includes(implementation)) throw new Error('Declare implementation: complete|in-progress|not-started');
+  if (!['active', 'closed', 'unknown'].includes(sessionState)) throw new Error('Invalid session state');
+  if (claim && !['planned', 'in-progress', 'implemented-unverified', 'verified'].includes(claim)) throw new Error('Invalid claimed point status');
+  const { file, data, paths, run } = readWorkflow(handoff);
+  const block = data.blocks.find(b => b.id === id);
+  if (!block) throw new Error(`Unknown block: ${id}`);
+  const result = blockQuality(run, block);
+  const requiredVisual = (data.visualChecks ?? []).filter(check => check.block === id && check.required !== false);
+  const visualResults = requiredVisual.map(required => {
+    const attempts = (run?.visualChecks ?? []).filter(check => check.id === required.id);
+    const latest = attempts.at(-1);
+    const session = latest?.sessionKey && run.sessions.find(session => session.key === latest.sessionKey);
+    const executor = latest?.executor ?? 'subagent';
+    const attributed = session && (executor === 'subagent'
+      ? session.parent && (!latest.principalSession || session.parent === latest.principalSession)
+      : !session.parent && !session.agentId && (!latest.principalSession || session.key === latest.principalSession));
+    const valid = Boolean(executor === required.executor && latest?.block === required.block
+      && latest?.status === 'finished' && latest.skillLoaded === true && attributed
+      && required.criteria.every(criterion => latest.results.some(r => r.criterion === criterion && r.status === 'pass')));
+    return { id: required.id, executor: required.executor, status: valid ? 'verified' : 'unverified', attempt: latest?.id ?? null,
+      durationMs: latest?.finishedAt ? Date.parse(latest.finishedAt) - Date.parse(latest.startedAt) : null };
+  });
+  const visualReady = visualResults.every(check => check.status === 'verified');
+  const status = implementation === 'not-started' ? 'planned' : implementation === 'in-progress' ? 'in-progress'
+    : result?.quality === 'verified' && visualReady ? 'verified' : 'implemented-unverified';
+  const criteria = block.criteria.map(id => {
+    const e = run?.evidence.filter(e => e.criterion === id).at(-1);
+    return { id, recordedStatus: e?.status ?? null, evidence: e?.path ?? null,
+      verification: run ? blockQuality(run, { criteria: [id] }).quality : 'not-checked' };
+  });
+  const warnings = [];
+  let registration = 'not-applicable';
+  if (run) {
+    const session = run.sessions.find(s => s.key === sessionKey);
+    registration = !sessionKey ? 'identity-pending' : !session ? 'not-registered' : 'registered';
+    if (!session) warnings.push('Identify and register this session explicitly; do not select the latest project log automatically.');
+    if (session) {
+      if (!session.coverageConfirmed) warnings.push('Session scope and subagent coverage are not confirmed.');
+      if (!session.configurationId) warnings.push('Session skill configuration is not attributed. Capture and associate it at entry; do not infer historical configuration from current files.');
+      warnings.push(...session.metrics.warnings);
+      if (!fs.existsSync(session.log) || hash(fs.readFileSync(session.log)) !== session.metrics.sourceHash) warnings.push('Session log changed or is unavailable: collect is required before final accounting.');
+    }
+    if (sessionState !== 'closed') warnings.push('Usage is provisional; collect again after the session closes.');
+  } else warnings.push(`Measurement ${data.measurement.status}: only structure and links checked, not acceptance evidence.`);
+  for (const visual of visualResults.filter(check => check.status !== 'verified')) warnings.push(`${visual.id}: ${visual.executor} denisco-visual-check evidence is missing, incomplete or not loaded by the registered executor.`);
+  if (claim && claim !== status) warnings.push(`Claim ${claim} contradicts computed status ${status}.`);
+  const continuation = nextBlock === undefined ? null : nextPrompt({ handoff, block: nextBlock, check: true });
+  if (continuation && !continuation.valid) warnings.push(`Continuation prompt ${continuation.status}: save the assigned prompt in STATE before handoff.`);
+  return { workflow: file, block: id, paths, implementation, status, verification: result?.quality ?? 'not-checked',
+    passed: result?.passed ?? null, required: result?.required ?? null, criteria,
+    measurement: { status: data.measurement.status, run: data.measurement.run ?? null, registration, sessionState },
+    claimMatches: !claim || claim === status, warnings,
+    ...(continuation ? { continuation } : {}), visualChecks: visualResults,
+    dependencies: block.dependsOn.map(id => ({ block: id, verification: blockQuality(run, data.blocks.find(b => b.id === id))?.quality ?? 'not-checked' })),
+    limitation: 'Evidence integrity is not semantic proof. Dependency readiness and Markdown consistency require review; this command neither reads claims from prose nor proves implementation completeness.' };
+}
+
+export const benchPath = () => fileURLToPath(new URL('./bench.mjs', import.meta.url));
+
+// Prompts stay short: ownership, evidence reconciliation and authorization rules live in
+// denisco-handoff-implementation, and task-specific constraints live in STATE.
+
+// Specification can deliver this before PLAN, STATE or an planned block exists.
+export function planningPrompt({ handoff, save = false, check = false }) {
+  if (save && check) throw new Error('Choose only one of --save or --check');
+  const context = readWorkflow(handoff, { draft: true });
+  const { data, paths } = context;
+  const fingerprint = value => hash(JSON.stringify({ data: value.data, paths: value.paths }));
+  const contextHash = fingerprint(context);
+  const measurement = data.measurement.status === 'enabled'
+    ? `Measurement is explicitly enabled and bound to ${data.measurement.run}. Use denisco-workflow-benchmark to register this conversation, preserve the binding and collect/report at closure. Keep identifiers internal.`
+    : data.measurement.status === 'disabled'
+      ? 'Measurement is disabled. Preserve measurement.status as disabled in every later session. Do not initialize, discover or invoke measurement tooling or registers.'
+      : 'Measurement status is unknown. Treat measurement as inactive: do not initialize, discover or invoke measurement tooling or registers unless a current explicit activation request is recorded.';
+  const prompt = `Use denisco-handoff-implementation with ${paths.handoff}.\nPhase: planning only. Read the handoff and operational context ${context.file}; read ${paths.plan} and ${paths.state} if present, preserving existing decisions and progress.\nCheck the handoff's blocker table and permission list; ask in chat about any unresolved item before choosing blocks.\nDeliver PLAN, STATE, the complete block map and a saved, checked first execution prompt. Do not implement application code in this phase.\nOnce they are saved, choose the execution path as denisco-handoff-implementation specifies: prepare coordination and ask its start question, or ask the user "Plan ready. Start <first block>?". Only the user's yes to the start question starts implementation; native plan approval, automatic mode or generic transition text do not.\n${measurement}\nIn Plan Mode propose the documents and first execution prompt in chat and name pending writes. Link the saved STATE prompt in the final response.\n`;
+  const args = { state: paths.handoff, block: 'planning', prompt, contextHash };
+  const result = save ? updateStatePrompt({ ...args, validateContext: () => {
+    if (fingerprint(readWorkflow(handoff, { draft: true })) !== contextHash) throw new Error('Workflow changed during planning prompt update');
+  } }) : check ? checkStatePrompt(args) : { status: 'printed', prompt };
+  const { state, ...output } = result;
+  return { ...output, handoff: paths.handoff, stage: 'planning' };
+}
+
+// One command at block entry: refresh registered usage, then show
+// the register and the assignment. Its only write is the reimport of already registered logs.
+export function open({ handoff, block: id, phase, nonce, provider }) {
+  const { data, paths, run } = readWorkflow(handoff);
+  const block = data.blocks.find(b => b.id === id);
+  if (!block) throw new Error(`Unknown planned block: ${id}`);
+  if (provider !== undefined && !['codex', 'claude'].includes(provider)) throw new Error('Invalid provider');
+  if (phase !== undefined && !['exploration', 'specification', 'planning', 'implementation', 'verification', 'correction'].includes(phase)) throw new Error('Invalid phase');
+  const warnings = [];
+  let accounting = { collected: false, sessions: [] }, register = null;
+  if (run) {
+    const before = new Map(run.sessions.map(s => [s.key, s.metrics.usage.total]));
+    // Refresh file snapshots; this does not establish that another conversation ended.
+    const refreshed = collect(data.measurement.run);
+    accounting = { collected: true, sessions: refreshed.sessions.map(s => ({ key: s.key, phase: s.phase,
+      state: usageState(s), total: s.metrics.usage.total,
+      delta: s.metrics.usage.total === null || before.get(s.key) == null ? null : s.metrics.usage.total - before.get(s.key) })) };
+    const summary = summarize(refreshed);
+    register = { quality: summary.quality, passed: summary.passed, required: summary.required,
+      review: summary.review.status, sessions: summary.sessions,
+      criteria: refreshed.criteria.map(c => ({ id: c.id, block: data.blocks.find(b => b.criteria.includes(c.id))?.id ?? null,
+        status: refreshed.evidence.filter(e => e.criterion === c.id).at(-1)?.status ?? 'not-run' })) };
+    warnings.push(...summary.warnings);
+  } else warnings.push(`Measurement ${data.measurement.status}: no usage is collected and acceptance cannot be verified automatically.`);
+  const continuation = nextPrompt({ handoff, block: id, check: true });
+  if (!continuation.valid) warnings.push(`Assigned prompt is ${continuation.status}: confirm this block is the authorized assignment before working.`);
+  const marker = nonce ?? `wfbench-${crypto.randomUUID()}`;
+  const identity = run ? {
+    marker,
+    whoami: `node ${benchPath()} whoami --provider ${provider ?? '<codex|claude>'} --project ${run.project} --nonce ${marker}`,
+    session: `node ${benchPath()} session --run ${data.measurement.run} --provider ${provider ?? '<codex|claude>'} --id <NATIVE_ID> --log <LOG> --phase ${phase ?? '<PHASE>'}`,
+    note: 'Emit the marker from a tool call, then resolve it with whoami; if no log carries it yet, repeat in a later call. Never select a log by recency.'
+  } : null;
+  return { block: id, paths, points: block.points, criteria: block.criteria, dependsOn: block.dependsOn,
+    measurement: { status: data.measurement.status, run: data.measurement.run ?? null },
+    accounting, register, continuation, identity, warnings,
+    limitation: 'Collect refreshes only registered logs. A session nobody registered stays invisible, and coverage remains an operator attestation.' };
+}
+
+// One command at closure: persist the assigned continuation, check the block, refresh usage.
+// It attests nothing: coverage, acceptance and the claimed status stay with the operator.
+export function close({ handoff, block: id, implementation, nextBlock, final = false, sessionKey, sessionState, claim, ticket }) {
+  if (Boolean(nextBlock) === Boolean(final)) throw new Error('Declare exactly one continuation: --next-block ID or --final');
+  const applied = [];
+  try {
+    if (ticket) {
+      if (sessionKey) throw new Error('Choose --ticket or --session-key');
+      realFile(ticket);
+      const request = readJSON(ticket), context = readWorkflow(handoff);
+      if (request.schemaVersion !== 1 || !request.handoff || !request.run || !context.run
+          || !samePath(request.handoff, context.paths.handoff) || !samePath(request.run, context.data.measurement.run)
+          || request.runId !== context.run.id) throw new Error('Registration ticket binding does not match this handoff');
+      const attempt = context.run.registrationAttempts?.find(a => samePath(a.ticket, ticket));
+      if (attempt?.status !== 'registered' || !context.run.sessions.some(s => s.key === attempt.sessionKey)) throw new Error('Registration ticket is not registered; resolve tracking before using it to close');
+      sessionKey = attempt.sessionKey;
+      sessionState ??= 'active';
+    }
+    const continuation = final ? nextPrompt({ handoff, clear: true }) : nextPrompt({ handoff, block: nextBlock, save: true });
+    applied.push(final ? 'next-prompt --clear' : `next-prompt --save --block ${nextBlock}`);
+    const result = checkpoint({ handoff, block: id, implementation, sessionKey, sessionState, claim,
+      ...(final ? {} : { nextBlock }) });
+    applied.push('checkpoint');
+    const { data, run } = readWorkflow(handoff);
+    const runFile = data.measurement.run ?? null;
+    let accounting = { collected: false, sessions: [] };
+    const remaining = [];
+    if (run) {
+      // Usage stays provisional while this conversation is active; the next read refreshes it.
+      const refreshed = collect(runFile);
+      applied.push('collect');
+      accounting = { collected: true, sessions: refreshed.sessions.map(s => ({ key: s.key, phase: s.phase, state: usageState(s), total: s.metrics.usage.total })) };
+      remaining.push(`Agent/observer: refresh again after this conversation closes with collect --run ${runFile}; do not infer closure from another conversation starting.`);
+      remaining.push(`Agent: regenerate the report with report --run ${runFile}; retain pending trailing usage while this conversation is active.`);
+      if (refreshed.sessions.some(s => !s.coverageConfirmed)) remaining.push('Coverage is unconfirmed: review scope and subagents, then collect --coverage-confirmed. Never pass it automatically.');
+      if (refreshed.review.status !== 'accepted') remaining.push('User acceptance is still pending: record it with review when the user gives it.');
+    }
+    return { ...result, applied, continuation, accounting, remaining };
+  } catch (error) {
+    error.message = `${error.message} (applied before failing: ${applied.join(', ') || 'nothing'})`;
+    throw error;
+  }
+}
+
+export function nextPrompt({ handoff, block: id, save = false, check = false, clear = false }) {
+  if ([save, check, clear].filter(Boolean).length > 1) throw new Error('Choose only one of --save, --check or --clear');
+  if (clear && id !== undefined) throw new Error('--clear does not accept --block');
+  const context = readWorkflow(handoff);
+  const { data, paths } = context;
+  const fingerprint = ({ data, paths }) => hash(JSON.stringify({ data, paths }));
+  const contextHash = fingerprint(context);
+  const validateContext = () => {
+    if (fingerprint(readWorkflow(handoff)) !== contextHash) throw new Error('Workflow changed during prompt update; retry after review');
+  };
+  if (clear) return updateStatePrompt({ state: paths.state, clear: true, validateContext });
+  const block = data.blocks.find(b => b.id === id);
+  if (!block) throw new Error(`Unknown planned block: ${id}`);
+  const measurement = data.measurement.status === 'enabled'
+    ? `Measurement run: ${data.measurement.run}\nBenchmark task: ${data.measurement.taskId}; project task: ${data.taskId}.\nUse denisco-workflow-benchmark track with this handoff, actual provider and phase; execute its returned nextCall yourself in a separate tool call. Keep tickets and identifiers internal, never pass them to the next conversation or ask the user to fill them. Register attributable children with evidenced parent links.\nRegistration/accounting from previous sessions may still be pending: inspect the register, do not assume completion.\nRecord evidence after final validation. Usage is provisional until collect after session closure. Never confirm coverage automatically.\nUse open with this handoff and block ${id} to refresh registered usage and inspect the assignment.\nWhen this session stops, close with denisco-workflow-benchmark close for this handoff and the last block worked, the actual implementation state, and the proposed next block or same-block resume (or --final when no task work remains, or the user ends the task or asks for no prompt). It saves the continuation, checkpoints and refreshes usage. The agent also generates report; trailing live usage and user acceptance remain pending where applicable.`
+    : data.measurement.status === 'disabled'
+      ? 'Measurement is disabled. Preserve measurement.status as disabled in every later session. Do not initialize, discover or invoke measurement tooling or registers. Record verification evidence in STATE.md.'
+      : 'Measurement status is unknown and remains inactive. Do not initialize, discover or invoke measurement tooling or registers without a current explicit activation request. Record verification evidence in STATE.md.';
+  const visual = (data.visualChecks ?? []).filter(check => check.block === id && check.required !== false);
+  const principal = visual.filter(check => check.executor === 'principal');
+  const delegated = visual.filter(check => check.executor === 'subagent');
+  const describe = checks => checks.map(check => `${check.id} (${check.criteria.join(', ')})`).join('; ');
+  const visualInstruction = visual.length ? `Visual checks: ${principal.length ? `execute in the principal session: ${describe(principal)}.` : ''} ${delegated.length ? `Delegated assignments in the map: ${describe(delegated)}. Verify that the current user request explicitly delegates these checks; an old map alone is not permission to launch a child. Reconcile future assignments with the user request without relabeling historical attempts. For a requested delegation, give each child an exclusive attempt directory and prohibit source, task-state, register and shared-tooling writes.` : 'Do not delegate the whole visual check unless the user requests it.'} Reconcile existing evidence before repeating a check. Load denisco-visual-check explicitly, start each attempt with visual-start --executor principal|subagent as assigned, and finish with visual-finish using the registered executor session and actual results/evidence. For perceptual criteria only, use a fresh blind judge when available and permitted. Register its attributable native log separately; it does not replace the denisco-visual-check executor. Keep measured source and capture tooling stable during capture. Close resources created solely for the check, preserving pre-existing services and resources explicitly needed for subsequent work. The principal merges shared records serially.` : '';
+  const prompt = [
+    `Use denisco-handoff-implementation to continue task ${data.taskId} (${paths.handoff}) from block ${id}.`,
+    `Read ${paths.state} first: Your actions, pending blockers and the next step are there. Plan: ${paths.plan}. Workflow context: ${workflowPath(handoff)}.`,
+    `Block ${id}: points ${block.points.join(', ')}; criteria ${block.criteria.join(', ')}; depends on ${block.dependsOn.join(', ') || 'no other block'}.`,
+    measurement,
+    visualInstruction
+  ].filter(Boolean).join('\n') + '\n';
+  const options = { state: paths.state, block: id, prompt, contextHash };
+  if (check) return checkStatePrompt(options);
+  if (save) return updateStatePrompt({ ...options, validateContext });
+  return prompt;
+}