@deniscodp/skills 0.0.0-stage → 1.0.0

package/scripts/install.mjs

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hash, inside, readJSON, writeJSON, rejectSymlinkPath } from '../skills/denisco-workflow-benchmark/scripts/io.mjs';
+import { ownership } from '../skills/denisco-handoff-implementation/scripts/ownership.mjs';
+import { discoverSkills, repository } from './catalog.mjs';
+
+export { repository } from './catalog.mjs';
+
+// Managed skills installed under an earlier name. An unmodified old copy is removed when the
+// renamed skill is installed in the same root; a modified one stops the installation.
+export const renamedSkills = Object.freeze({
+  'project-context': 'denisco-project-context',
+  'interactive-spec-definition': 'denisco-interactive-spec-definition',
+  'handoff-implementation': 'denisco-handoff-implementation',
+  'implementation-coordinator': 'denisco-implementation-coordinator',
+  'visual-check': 'denisco-visual-check',
+  'workflow-benchmark': 'denisco-workflow-benchmark'
+});
+
+// Git with core.autocrlf rewrites line endings on checkout, stash or stage. A copy that differs from
+// a recorded digest only in CRLF/LF is the same managed content, not a local modification.
+const toLF = content => Buffer.from(content.toString('utf8').replace(/\r\n/g, '\n'));
+const toCRLF = content => Buffer.from(toLF(content).toString('utf8').replace(/\n/g, '\r\n'));
+function sameContent(content, digest) {
+  return typeof digest === 'string' && [content, toLF(content), toCRLF(content)].some(variant => hash(variant) === digest);
+}
+
+// Skills root inside the project for each provider. Codex, Antigravity (agy) and Gemini CLI all read
+// <project>/.agents/skills, so they share one installation and one manifest.
+export const providerRoots = Object.freeze({
+  claude: path.join('.claude', 'skills'),
+  codex: path.join('.agents', 'skills'),
+  agy: path.join('.agents', 'skills'),
+  gemini: path.join('.agents', 'skills')
+});
+
+// `external` holds skills already downloaded into memory ({ name, files: Map<relative, Buffer> }).
+// They share the root's manifest and its update/conflict rules; in addition, an existing folder of
+// the same name that the manifest does not manage is a conflict instead of being adopted.
+export function planInstall({ target, provider, source = repository, withoutBenchmark = false, exclude = [], external = [] }) {
+  if (!Object.hasOwn(providerRoots, provider)) throw new Error(`provider must be one of: ${Object.keys(providerRoots).join(', ')}`);
+  const excluded = [...new Set([...(withoutBenchmark ? ['denisco-workflow-benchmark'] : []), ...exclude])];
+  const packaged = discoverSkills(source).filter(skill => !excluded.includes(skill.name));
+  for (const skill of external) {
+    if (packaged.some(p => p.name === skill.name)) throw new Error(`Downloaded skill ${skill.name} clashes with a packaged skill`);
+  }
+  const skills = [...packaged, ...external.map(({ name, files }) => ({ name, files: [...files.keys()], contents: files }))];
+  if (!fs.statSync(target).isDirectory()) throw new Error('Target project must exist');
+  const root = path.join(path.resolve(target), providerRoots[provider]);
+  rejectSymlinkPath(root);
+  const manifestPath = path.join(root, '.workflow-install.json');
+  rejectSymlinkPath(manifestPath);
+  const previous = fs.existsSync(manifestPath) ? readJSON(manifestPath) : { schemaVersion: 1, files: {} };
+  if (previous.schemaVersion !== 1 || !previous.files || typeof previous.files !== 'object') throw new Error('Invalid installation manifest');
+  const entries = [], unmanaged = [];
+  for (const { name, directory: sourceDir, files, contents } of skills) {
+    if (contents) {
+      const folder = inside(root, name);
+      rejectSymlinkPath(folder);
+      if (fs.existsSync(folder) && !Object.keys(previous.files).some(key => key.startsWith(`${name}/`))) unmanaged.push(name);
+    }
+    for (const relative of files) {
+      const key = `${name}/${relative}`, destination = inside(root, key);
+      rejectSymlinkPath(destination);
+      const content = contents ? contents.get(relative) : fs.readFileSync(path.join(sourceDir, relative)), wanted = hash(content);
+      const existing = fs.existsSync(destination) ? fs.readFileSync(destination) : null;
+      const current = existing ? hash(existing) : null;
+      const action = existing === null ? 'create' : sameContent(existing, wanted) ? 'unchanged'
+        : sameContent(existing, previous.files[key]) ? 'update' : 'conflict';
+      entries.push({ key, destination, wanted, current, action, content });
+    }
+  }
+  const installed = new Set(skills.map(skill => skill.name));
+  const removals = [], stale = [];
+  for (const key of Object.keys(previous.files)) {
+    if (entries.some(e => e.key === key)) continue;
+    const oldName = key.split('/')[0];
+    if (!installed.has(renamedSkills[oldName])) { stale.push(key); continue; }
+    const destination = inside(root, key);
+    rejectSymlinkPath(destination);
+    const existing = fs.existsSync(destination) ? fs.readFileSync(destination) : null;
+    removals.push({ key, destination, action: existing === null ? 'gone' : sameContent(existing, previous.files[key]) ? 'remove' : 'conflict' });
+  }
+  return { root, manifestPath, entries, removals, stale, excluded, unmanaged };
+}
+
+// A writer holding the workflow claim in the target or in any of its linked worktrees may still
+// load the old package paths, because linked worktrees use the skills installed at the target.
+function worktrees(target) {
+  const list = [path.resolve(target)], linked = path.join(target, '.git', 'worktrees');
+  if (fs.existsSync(linked) && fs.statSync(linked).isDirectory()) {
+    for (const entry of fs.readdirSync(linked)) {
+      const gitdir = path.join(linked, entry, 'gitdir');
+      if (!fs.existsSync(gitdir)) continue;
+      const directory = path.dirname(path.resolve(linked, entry, fs.readFileSync(gitdir, 'utf8').trim()));
+      if (fs.existsSync(directory)) list.push(directory);
+    }
+  }
+  return list;
+}
+function activeWriter(target) {
+  for (const worktree of worktrees(target)) {
+    let status;
+    try { status = ownership({ action: 'status', worktree }); }
+    catch (error) {
+      if (/initialized Git worktree/.test(error.message)) continue; // no worktree, no claim
+      throw error;
+    }
+    if (status.status === 'owned') return { worktree, owner: status.owner };
+  }
+  return null;
+}
+
+// Skill names recorded in a root's manifest, with pre-prefix names mapped to their current name.
+export function manifestSkills(root) {
+  const manifestPath = path.join(root, '.workflow-install.json');
+  rejectSymlinkPath(manifestPath);
+  if (!fs.existsSync(manifestPath)) return new Set();
+  const manifest = readJSON(manifestPath);
+  if (manifest.schemaVersion !== 1 || !manifest.files || typeof manifest.files !== 'object') throw new Error('Invalid installation manifest');
+  return new Set(Object.keys(manifest.files).map(key => key.split('/')[0]).map(name => renamedSkills[name] ?? name));
+}
+
+export function summarizePlan(plan) {
+  return {
+    root: plan.root,
+    changes: [...plan.entries, ...plan.removals].map(({ key, action }) => ({ key, action })),
+    renamed: [...new Set(plan.removals.map(r => r.key.split('/')[0]))].map(from => ({ from, to: renamedSkills[from] })),
+    stale: plan.stale, excluded: plan.excluded, applied: false
+  };
+}
+
+// Every safety stop happens here, before any write. Callers installing several roots check all of
+// their plans first, so a stop in one root cannot leave another root partially written.
+export function checkPlan(plan, target) {
+  if ([...plan.entries, ...plan.removals].some(e => e.action === 'conflict') || plan.stale.length || plan.unmanaged?.length) {
+    throw new Error('Installation conflicts or stale managed files: review the dry-run; no files changed');
+  }
+  const writer = plan.removals.length ? activeWriter(target) : null;
+  if (writer) {
+    throw new Error(`A workflow writer holds the claim in ${writer.worktree}: rename migration deferred until it releases; no files changed`);
+  }
+}
+
+export function install(options) {
+  const plan = planInstall(options);
+  const summary = summarizePlan(plan);
+  if (!options.apply) return summary;
+  checkPlan(plan, options.target);
+  applyPlan(plan);
+  return { ...summary, applied: true };
+}
+
+export function applyPlan(plan) {
+  for (const entry of plan.entries) {
+    if (entry.action === 'unchanged') continue;
+    fs.mkdirSync(path.dirname(entry.destination), { recursive: true });
+    fs.writeFileSync(entry.destination, entry.content);
+  }
+  for (const removal of plan.removals) {
+    if (removal.action !== 'remove') continue;
+    fs.unlinkSync(removal.destination);
+    // Prune directories emptied by the removal, never the skills root or unmanaged content.
+    for (let dir = path.dirname(removal.destination); dir !== plan.root && dir.startsWith(plan.root); dir = path.dirname(dir)) {
+      if (fs.readdirSync(dir).length) break;
+      fs.rmdirSync(dir);
+    }
+  }
+  writeJSON(plan.manifestPath, { schemaVersion: 1, files: Object.fromEntries(plan.entries.map(e => [e.key, e.wanted])) });
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const args = process.argv.slice(2), options = {};
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--apply') options.apply = true;
+      else if (args[i] === '--without-benchmark') options.withoutBenchmark = true;
+      else if (['--target', '--provider'].includes(args[i])) options[args[i].slice(2)] = args[++i];
+      else throw new Error('Usage: node scripts/install.mjs --target <project> --provider codex|claude [--without-benchmark] [--apply]');
+    }
+    if (!options.target) throw new Error('Explicit --target required');
+    console.log(JSON.stringify(install(options), null, 2));
+  } catch (e) { console.error(e.message); process.exitCode = 1; }
+}

package/scripts/recommended.mjs

@@ -0,0 +1,102 @@
+import { skillFrontmatter } from './catalog.mjs';
+
+// Recommended third-party skills, downloaded at install time from the latest commit of `ref`.
+// Adding one needs only a new entry here: `path` is the skill folder inside the repository and its
+// last segment must equal `name`; `requires` lists catalog entries installed with it.
+export const recommendedSkills = Object.freeze([
+  {
+    name: 'grill-me',
+    description: 'relentless interview about a plan or decision',
+    repo: 'mattpocock/skills', ref: 'main', path: 'skills/productivity/grill-me',
+    requires: ['grilling'], license: 'MIT', author: 'Matt Pocock'
+  },
+  {
+    name: 'grilling',
+    description: 'the grilling procedure used by grill-me',
+    repo: 'mattpocock/skills', ref: 'main', path: 'skills/productivity/grilling',
+    requires: [], license: 'MIT', author: 'Matt Pocock'
+  }
+]);
+
+const byName = new Map(recommendedSkills.map(skill => [skill.name, skill]));
+export const isRecommended = name => byName.has(name);
+
+// The chosen names plus every recommended skill they require, transitively.
+export function withDependencies(names) {
+  const result = new Set();
+  const visit = name => {
+    if (result.has(name)) return;
+    result.add(name);
+    for (const dependency of byName.get(name)?.requires ?? []) visit(dependency);
+  };
+  names.forEach(visit);
+  return [...result];
+}
+
+// Catalog entries that require `name` and are among `chosen`.
+export const requiredBy = (name, chosen) => recommendedSkills.filter(s => chosen.includes(s.name) && s.requires.includes(name)).map(s => s.name);
+
+export class DownloadError extends Error {}
+
+const API = 'https://api.github.com', RAW = 'https://raw.githubusercontent.com';
+const encodePath = value => value.split('/').map(encodeURIComponent).join('/');
+
+async function request(fetchImpl, url, { token, accept } = {}) {
+  const headers = { 'User-Agent': 'deniscodp-skills-installer' };
+  if (accept) headers.Accept = accept;
+  // The token only goes to the GitHub API and never appears in messages.
+  if (token && url.startsWith(API)) headers.Authorization = `Bearer ${token}`;
+  let response;
+  try {
+    response = await fetchImpl(url, { headers, redirect: 'follow', signal: AbortSignal.timeout(30000) });
+  } catch (error) {
+    throw new DownloadError(`network error for ${url}: ${error.message}`);
+  }
+  if (!response.ok) {
+    const limited = [403, 429].includes(response.status) && response.headers?.get?.('x-ratelimit-remaining') === '0';
+    throw new DownloadError(`HTTP ${response.status} for ${url}${limited ? ' (GitHub rate limit reached; wait or set GITHUB_TOKEN)' : ''}`);
+  }
+  return response;
+}
+
+// Downloads every file of the named catalog skills into memory before any plan is computed, so a
+// failure leaves the target untouched. Two GitHub API calls per repository (commit, recursive tree),
+// then one raw download per file at that exact commit.
+export async function downloadRecommended(names, { fetch: fetchImpl = globalThis.fetch, token = process.env.GITHUB_TOKEN } = {}) {
+  const wanted = names.map(name => {
+    const skill = byName.get(name);
+    if (!skill) throw new DownloadError(`not a recommended skill: ${name}`);
+    return skill;
+  });
+  const commits = new Map(), trees = new Map(), downloaded = [];
+  for (const skill of wanted) {
+    const origin = `${skill.repo}@${skill.ref}`;
+    if (!commits.has(origin)) {
+      const response = await request(fetchImpl, `${API}/repos/${skill.repo}/commits/${encodeURIComponent(skill.ref)}`, { token, accept: 'application/vnd.github.sha' });
+      const commit = (await response.text()).trim();
+      if (!/^[0-9a-f]{40}$/.test(commit)) throw new DownloadError(`unexpected commit id for ${origin}`);
+      const tree = await (await request(fetchImpl, `${API}/repos/${skill.repo}/git/trees/${commit}?recursive=1`, { token, accept: 'application/vnd.github+json' })).json();
+      if (!Array.isArray(tree?.tree)) throw new DownloadError(`unexpected tree listing for ${origin}`);
+      if (tree.truncated) throw new DownloadError(`tree listing of ${origin} is truncated`);
+      commits.set(origin, commit);
+      trees.set(origin, tree.tree);
+    }
+    const commit = commits.get(origin), prefix = `${skill.path}/`;
+    const items = trees.get(origin).filter(item => item.path.startsWith(prefix) && item.type !== 'tree');
+    if (!items.length) throw new DownloadError(`${skill.path} not found in ${origin} (commit ${commit})`);
+    const files = new Map();
+    for (const item of items.sort((a, b) => a.path < b.path ? -1 : 1)) {
+      const relative = item.path.slice(prefix.length);
+      if (item.mode === '120000') throw new DownloadError(`symlink refused: ${item.path} in ${origin}`);
+      if (item.type !== 'blob') throw new DownloadError(`unsupported entry ${item.type}: ${item.path} in ${origin}`);
+      if (relative.split('/').some(segment => !segment || segment === '.' || segment === '..')) throw new DownloadError(`unsafe path: ${item.path}`);
+      const response = await request(fetchImpl, `${RAW}/${skill.repo}/${commit}/${encodePath(item.path)}`);
+      files.set(relative, Buffer.from(await response.arrayBuffer()));
+    }
+    if (!files.has('SKILL.md')) throw new DownloadError(`${skill.path}/SKILL.md missing in ${origin} (commit ${commit})`);
+    try { skillFrontmatter(files.get('SKILL.md').toString('utf8'), skill.name, `${origin}:${skill.path}/SKILL.md`); }
+    catch (error) { throw new DownloadError(error.message); }
+    downloaded.push({ name: skill.name, files, source: { repo: skill.repo, ref: skill.ref, commit, license: skill.license, author: skill.author } });
+  }
+  return downloaded;
+}

package/skills/denisco-handoff-implementation/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: denisco-handoff-implementation
+description: "Plan and execute a decided handoff block by block until a real stop, verify acceptance and keep task state current. Use for planning a decided bug fix or feature and implementing or resuming its blocks; not for open-ended product design or repository onboarding."
+metadata:
+  version: "8.3.0"
+---
+
+# Handoff implementation
+
+Input: handoff path, optional point/block assignment and existing plan/state paths.
+Legacy `punto 3` inputs remain valid. Preserve approved behavior and report discrepancies.
+For an explicit bounded assignment or a programmer dispatched by denisco-implementation-coordinator,
+read [bounded implementation](references/delegated-implementation.md). Its explicit block list and
+return boundary constrain the normal continue-until-stop loop; a starting block alone does not.
+The programmer owns technical document updates through this skill's existing procedures.
+COORDINATOR.md and COORDINATOR-HISTORY.md are read-only inputs owned by the coordinator;
+their grouping proposals never replace HANDOFF, PLAN, STATE or the operational block map.
+Even with only a handoff path, look for `<handoff-path>.workflow.json` and read
+[the operational context contract](references/session-plan.md) before entering or resuming.
+Before any task writes or measurement registration, follow [worktree ownership](references/ownership.md):
+inspect peers and acquire the single-writer claim with the installed helper. A second top-level
+instance stays read-only even when it shares this conversation ID. A delegated visual child has
+only its assigned artifact scope. This gate also applies when measurement is disabled; a claim
+coordinates execution and never supplies missing user authorization.
+Recover measurement only from this context or explicitly referenced task documents, never from
+unrelated registers. Measurement is disabled by default and `disabled` is authoritative across
+sessions. Do not load, install or use denisco-workflow-benchmark, search for a run, or change that state
+unless the current user request or applicable project instructions explicitly enable measurement
+for this task. `Unknown` is inert legacy/interrupted state, not permission to enable; preserve or
+resolve it to disabled unless explicit activation evidence exists. An unavailable measurement
+helper never blocks independent planning or implementation.
+
+In writable mode with measurement enabled and the helper available, at first entry (including
+planning) load denisco-workflow-benchmark and run `track --handoff <file>
+--provider <actual-provider> --phase <planning|implementation>`, then execute its returned
+nextCall yourself in a separate tool call. This works before PLAN/STATE and the block map exist.
+Keep technical identifiers internal; do not ask the user to assemble registration commands.
+If registration remains pending after one later retry, record the gap and continue independent work.
+Keep the returned ticket in this conversation. At closure pass that same ticket to
+`close --ticket <ticket>` when available; this reuses the resolved identity and prevents an
+`identity-pending` checkpoint. Do not copy it into the next session's prompt.
+
+## Enter at the right stage
+
+The user's request selects the phase, or the user's yes to a phase question the agent asked; file
+existence and tool mode do not. Read project instructions, handoff, operational context and
+existing PLAN/STATE first. Read assigned points and dependencies in full; preserve settled product
+decisions.
+
+Require scoped evidence before classifying a request as implementation. Bare native transition
+text such as `Implement the plan.`, `Start coding` or `Proceed` names neither a saved execution
+prompt nor a handoff/block assignment, is not the user's answer to a phase question, and is not
+implementation authorization. If it follows a specification or planning proposal whose artifacts
+are still pending, finish that existing phase and ask its phase question; do not reinterpret the
+verb "implement" as a new assignment.
+
+- **Planning only:** the prompt from HANDOFF, the user's yes to the specification's planning
+  question, or a handoff path without an execution assignment creates/reconciles PLAN, STATE and
+  the complete planned block map. First check the handoff's blocker table and permission list.
+  A handoff without them, or with an unresolved item, gets the blocker hunt from
+  [the blocker checklist](references/blocker-checklist.md) now, before blocks are chosen. Select
+  the first dependency-ready block and save/check its execution prompt in STATE. Then choose the
+  execution path. **Coordinated** is the default when the plan has two or more implementation
+  blocks (final integration excluded), denisco-implementation-coordinator is installed and the runtime can
+  create fresh-context workers, unless the user asked for direct execution: release the planning
+  claim, read the installed
+  denisco-implementation-coordinator `SKILL.md` by its path and continue with its preparation in this
+  conversation. Preparation writes only coordination documents, launches nothing and ends with its
+  own start question instead of the one below. Otherwise the path is **direct**: ask "Plan ready.
+  Start <block>?", naming the reason when the coordinator or fresh workers are unavailable. The user's yes starts
+  implementation in this conversation; any other answer ends planning without application-code
+  edits, also in automatic mode. With the question, mention that the saved prompt can instead
+  start it in a fresh conversation with less context.
+- **Implementation:** the user's yes to the start question, a user-submitted execution prompt or an
+  explicit scoped execution request authorizes implementing the plan from the named block. Record
+  that instruction, date and scope in STATE and proceed without another plan-approval question.
+  Generating or reading a prompt in a file is not a user request. Respect newer restrictions.
+  An authorized coordinator may dispatch a bounded assignment under the recorded user request;
+  preserve both that authorization and the narrower assignment in STATE.
+- **Resume:** establish ownership, inspect the worktree, STATE, results and attributable logs.
+  Distinguish absent, unregistered, stale and failed evidence before repeating checks. Documents
+  left missing by older sessions are repaired without replanning; a STATE in an older format is
+  migrated as the session plan describes.
+
+When a new human session starts on a task that already has STATE, go through **Your actions** first: ask
+which items are done and, in the same message, whether the user changed anything else since the
+last session (deploys, portals, configuration). Record the answers in STATE before continuing.
+An internal programmer rotation uses the coordinator's recorded answers and routes new questions
+through it, as the bounded implementation contract specifies.
+
+Use [session planning](references/session-plan.md) for the split and document contracts. Small
+tasks can have one block. A prepared block map does not claim that implementation was authorized.
+
+In Plan Mode propose only the current phase's deliverables and name pending writes. Once writing
+is permitted, materialize them and ask the phase question. Native plan approval or switching to
+automatic mode never advances from specification to planning or from planning to implementation.
+A private CLI plan does not replace the documents. Before asking the start question, verify actual
+PLAN, STATE, the complete block/criterion map and the saved/checked first execution prompt. Record
+the plan as prepared, preserving any historical approvals rather than inventing new ones.
+
+## Build the block
+
+Recheck anchors by path and symbol before editing. Record meaningful drift or invalidated assumptions.
+Reuse components, rules and endpoints. Respect rejected alternatives, exclusions and shared invariants.
+Make routine technical decisions within agreed behavior.
+Iterate with the fastest feedback loop the operating guide documents (incremental watch/serve, an
+open browser session) and keep it running between edits. Reserve full builds and full probe runs
+for the evidence the criteria require, once the code is stable. Send the full output of test suites
+and builds to a log file and read only the summary and the failures; open the log around a failure
+when its context is needed. A full log read into the conversation stays in context and is paid
+again at every later step.
+
+When something needs the user, ask at once in chat, in the format of the blocker checklist's Asking
+section, and keep working on the parts it does not block. Once answered, record the answer and
+continue in this session. If nothing else can proceed and the turn ends waiting, first checkpoint
+STATE with progress, unrecorded evidence, running services and the open question, so a cleared or
+interrupted conversation can resume from disk. Every change in scope stays visible in PLAN and STATE:
+
+- **Blocker found late:** ask as above; record the answer where it applies and in STATE.
+- **Split:** dividing a point needs no question when it adds no user action and no permission;
+  record it in PLAN. A part that needs either is a new point.
+- **New point for the same goal:** run the blocker hunt for that point only, in chat. Edit the
+  handoff point in place, moving the replaced text to STATE-HISTORY.md, update PLAN and the block
+  map, then continue.
+- **New goal:** a request that adds a goal instead of finishing a point belongs to a new task.
+  Propose closing or pausing this task, then use denisco-interactive-spec-definition for the new one.
+- **Permissions:** act within the handoff's permission list; ask before any other action and before
+  every always-ask action in the blocker checklist.
+- **Recurring tool permission:** the first time a command needs a tool permission or sandbox
+  escalation that the project does not grant yet, propose a permanent project entry: command
+  pattern, settings file and reason. After the user's yes, add it and record it in the operating
+  guide. Permission settings change only with that yes.
+
+An excluded point elsewhere stops this block only if it is a dependency.
+
+## Verify by requirement
+
+Run the mandatory project cycle and assigned acceptance criteria. Use the operating guide for
+commands, environment, login, roles and data. Exercise the motivating edge case and related consumers.
+
+- Technical behavior: focused tests, type/build checks or API checks.
+- UI interaction: walk the flow and inspect effects and console after interaction. Explore
+  interactively when a browser tool is available and script only the final evidence. Before
+  rerunning a failed browser check, read its captured console and network errors; once a backend
+  failure is confirmed, use an authorized fallback or report the outage instead of retrying.
+- Numeric visual requirements and parity with an existing element: measure resolved values and
+  rendered geometry in the browser.
+- Perceptual requirements: use `denisco-visual-check` for the stated comparisons when available.
+
+When criteria use denisco-visual-check, the implementation owner loads the skill and performs measurements/captures.
+For a coordinated programmer, apply the bounded contract's visual roles and native measurement
+attribution; the following default describes direct execution and separately delegated visual checks.
+New sidecar entries use executor "principal". Delegate the whole check only when the user explicitly
+requests it, recording executor "subagent". Keep existing historical attempts; an old delegated map
+is not fresh user authorization to launch a child. Reconcile the future assignment with the current
+request and preserve previous results. The only automatic visual delegation is a fresh blind judge
+for perceptual criteria when available and permitted by the environment.
+With measurement enabled, register visual-start with the explicit executor before the attempt,
+refresh/register that executor's native log, then visual-finish with results and evidence. Register
+the blind judge separately for usage; it does not replace the denisco-visual-check executor or load its skill.
+For an explicitly delegated check, give the child an exclusive attempt directory, prohibit source,
+PLAN/STATE, sidecar, register and shared-tooling writes, and merge returned index rows serially.
+Finish pre-edit capture before source edits and keep source/tooling stable during post-edit capture.
+Apply fixes after capture, then recheck affected criteria. Follow denisco-visual-check's resource cleanup
+contract on success, failure and cancellation; return/close children before releasing ownership.
+
+A UI file change alone does not require a blind judge. Mockups never verify implementation.
+A criterion whose verifier is the user passes on the user's report, recorded as such; a waived
+criterion stays listed with its reason. If a required check cannot run, complete the independent
+checks and ask once: waive it with a reason, rewrite the criterion, or let the user verify it.
+A perceptual criterion still failing after denisco-visual-check's single correction round gets the same
+question, with the images and measurements.
+Until answered the point is **implemented-unverified**. Rerun a failed check in a later session
+only when a relevant fact has changed. Do not remove the criterion or claim weaker evidence proves it.
+Failed measurements prevent visual sign-off, not reporting or independent diagnostics.
+
+## Run until a real stop
+
+When a block is finished (verified, or implemented-unverified with its gaps named), update STATE and
+continue with the next dependency-ready block in this conversation within the explicit assignment.
+Stop when:
+
+1. the task's **Done when** is met;
+2. the remaining work waits on something outside this conversation: a your-action item not yet
+   done, a third-party review, propagation, or a check that needs time to pass;
+3. the conversation has grown too long to keep track of reliably;
+4. the user says stop.
+5. the explicitly bounded assignment ends, or its programmer checkpoints early for context pressure,
+   a blocker or an explicit limit and returns control under the bounded implementation contract.
+
+"From B1" remains a starting point, not a one-block boundary. "Only B1-B2, then return" is bounded.
+Do not start B3 after that boundary, even if it is ready. A worker does not enlarge its own assignment.
+
+A question the user answers in this conversation is not a stop. Before stopping, persist and hand over.
+
+## Persist and hand over
+
+Follow [the plan and state contract](references/session-plan.md): STATE is the current picture,
+STATE-HISTORY.md receives each session's entry, PLAN is the block map. Record implementation status,
+criterion results/evidence, blockers, structural changes and meaningful drift per point.
+Preserve failures and reopenings. A verification gap is not a completed point.
+Never label a point/block `verified except ...` or `complete and verified` while a required
+criterion is unavailable. With finished code use `implemented-unverified` and name the gaps.
+Report dependency readiness separately: explain why an unresolved check does or does not prevent
+the next block; neither silently declare it ready nor block unrelated work.
+
+End every session's final message with **Your actions**, the same list as in STATE, or "Nothing
+needed from you."
+
+When the session stops with task work remaining, save the short next prompt in STATE.md for the
+next dependency-ready block or the unfinished one; a later user request or an already authorized
+coordinator launches the next assignment. The current programmer never launches its successor. A
+user stop with work remaining is a pause: save the prompt as for any other stop and record the stop
+in STATE; the stop holds because only a later user request sends the prompt. Omit or clear it only
+when the user ends the task or asks for no prompt, recording the reason. Keep environment facts in the
+operating guide and evidence paths in STATE. Prompts relay decisions, never invent them.
+Include native session registration when tracking is active.
+When enabled, use denisco-workflow-benchmark to record actual evidence and an identifiable native session.
+After agent-managed registration and once the block map exists, use `open --handoff <file>
+--block <id>` to refresh registered usage and inspect the assignment. Its legacy identity hints
+are internal; `track` handles identification and registration together.
+Planning and implementation in one session count once. After each block's final validation and
+evidence registration, update STATE and run the read-only `checkpoint` for that block. When the
+session stops, use `next-prompt --save` for the proposed next assignment and run `checkpoint` for
+the last block worked with `--next-block` naming that continuation; reconcile both technical status
+and prompt delivery with STATE and the final response. A resume may assign the same unfinished
+block. Missing identity stays pending, never guessed or counted as zero.
+With measurement disabled/unknown, save and reread the prompt manually without loading or installing
+denisco-workflow-benchmark. Automatic benchmark prompt checking is intentionally unavailable in that mode.
+In Plan Mode propose the prompt and leave persistence pending; never claim it was saved.
+Link the saved STATE section in the response; any prompt repeated in chat must be the saved text.
+Further code/evidence changes require refreshed results and another checkpoint before closing.
+`close --handoff <file> --block <id> --implementation <state> (--next-block <id>|--final)` performs
+the save and the checkpoint in one step and refreshes usage; the separate commands stay equivalent.
+Prefer `--ticket <ticket>` from the same conversation over repeating a native session key.
+Live usage remains provisional. The agent refreshes it with `collect` and generates `report` at
+closure; the next entry refreshes again. The last conversation's trailing usage remains pending
+until an observer can refresh its closed log. Never require user-managed IDs or attest closure
+just because another conversation has started.
+
+When all blocks are implemented, check cross-block integration and complete acceptance.
+In coordinated mode the coordinator assigns this to a fresh integration worker; an implementation
+worker records that pending step and returns without exceeding its boundary or claiming task completion.
+When no task work remains, or the user ends the task or asks for no prompt, use `next-prompt --clear` to remove the obsolete generated
+section (or remove the old prompt manually without a helper), and checkpoint without `--next-block`.
+Preserve pending verification, accounting and acceptance in STATE; clearing is not proof of completion.
+Reconcile PLAN/STATE current status with the latest authorization, worktree and checkpoint;
+move obsolete planning-only claims to STATE-HISTORY.md. Report passed, failed and
+unavailable checks, pre-existing issues and evidence locations.
+Technical verification permits `verified`; user acceptance/reopening is recorded separately,
+never inferred from the agent's closing message.
+After children have returned and all validation, state and reporting writes are finished, release
+the execution claim. A conflict never resolves merely because the other worktree files went quiet;
+use the explicit transfer/recovery procedure in the ownership contract.

package/skills/denisco-handoff-implementation/references/blocker-checklist.md

@@ -0,0 +1,71 @@
+# Blocker checklist
+
+A **blocker** is anything the agent cannot settle alone that would stop or reshape the work: a fact
+only the user knows, an action only the user or a third party can take, a permission, or a check
+the agent cannot run. The **blocker hunt** finds them before the work they affect starts.
+
+## Probe first
+
+Settle by looking whatever looking can settle, then ask about the rest:
+
+- Read the official requirements of every external platform the task touches (submission, review,
+  publication, authentication, hosting limits). Record the links and each requirement found.
+- Run the project's verification cycle once and record the failures that already exist.
+- Validate a draft configuration or manifest when a validator exists.
+- Check what you can operate here: portals and dashboards, an authenticated browser, GUI clients,
+  media files, push and deploy. Every step you cannot operate is a step for the user.
+
+## Categories
+
+Name the concrete value for each category, or ask for it. Skip a category only when the task
+cannot touch it.
+
+| Category | Settle |
+|---|---|
+| Accounts and credentials | which account, who holds it, where the secret lives (never its value) |
+| Console and portal access | which console, organization and project; who can sign in |
+| Who operates each step | for every portal, GUI or physical step: the agent or the user |
+| Permissions | the permission list below |
+| Environments | staging or production, which domain, which data |
+| Size facts | facts that change how much to build: how many users, existing data, whether data may be lost |
+| Product decisions | choices only the user can make |
+| Third-party waits | reviews, approvals, propagation; expected duration; what the plan does meanwhile |
+| Paid services | which plan, who pays, limits that stop the work |
+| Legal and content | texts, policies and media the user must supply or approve |
+| Checks the agent cannot run | who verifies each one, below |
+
+## Close every item
+
+Each item ends in exactly one state:
+
+- **decided:** the answer is recorded where it applies;
+- **your action:** the user agreed to do it; the item names the point it unblocks and how the agent
+  will check it, and it appears in **Your actions**;
+- **not in this task:** moved out of the task with the user's yes.
+
+An item never asked, or recorded as unknown, is still open, and the work that depends on it is not
+ready.
+
+## Permission list
+
+Ask once for the actions the agent may take during this task without asking again. Each entry
+names the action, its target and its limit, for example: push to `auth/*` branches; deploy
+`mcp-service`; write to the staging database.
+
+These actions always need a fresh yes, even when listed: submitting or publishing to a store or
+portal; DNS and certificates; deleting or migrating production data; spending money; messages to
+real people. Ask before any action outside the list.
+
+## Who verifies
+
+Every acceptance criterion names its verifier:
+
+- **agent:** the agent runs the check;
+- **user:** the user performs it and reports; the report is the evidence;
+- **waived:** nobody runs it; record the reason and the user's yes.
+
+## Asking
+
+Ask in rounds. Number each question and give your recommended answer, so that "yes" accepts it.
+Put every question that is ready into the same round; a question that depends on another answer
+waits for the next round.