@deniscodp/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { hash, listFiles, mutateRun, now, rejectSymlinkPath, safeId } from './io.mjs';
+
+// Capture only a simple metadata.version scalar from the YAML frontmatter. This is not a
+// YAML validator: unfamiliar syntax remains unknown instead of adding a runtime dependency.
+export function declaredVersion(text) {
+  const frontmatter = text.replace(/^\uFEFF/, '').match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+  const metadata = frontmatter?.match(/^metadata:\s*\r?\n((?:[ \t]+[^\r\n]*\r?\n?)+)/m)?.[1];
+  const version = metadata?.match(/^ {2}version: *(?:"(\d+\.\d+\.\d+)"|'(\d+\.\d+\.\d+)'|(\d+\.\d+\.\d+)) *(?:#.*)?$/m);
+  return version ? version[1] ?? version[2] ?? version[3] : null;
+}
+export function snapshotConfiguration({ skillsRoot, note, loaded = [] }) {
+  if (!note?.trim()) throw new Error('Configuration requires an observation/provenance note');
+  if (!Array.isArray(loaded) || new Set(loaded).size !== loaded.length) throw new Error('Loaded skill names must be unique');
+  loaded.forEach(safeId);
+  const root = path.resolve(skillsRoot);
+  rejectSymlinkPath(root);
+  const skills = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.isSymbolicLink()) throw new Error('Symlink skill snapshot refused');
+    const directory = path.join(root, entry.name), skillFile = path.join(directory, 'SKILL.md');
+    if (!entry.isDirectory() || !fs.existsSync(skillFile)) continue;
+    safeId(entry.name);
+    const files = listFiles(directory).map(relative => ({ path: relative, sha256: hash(fs.readFileSync(path.join(directory, relative))) }));
+    const version = declaredVersion(fs.readFileSync(skillFile, 'utf8'));
+    skills.push({ name: entry.name, path: directory, declaredVersion: version, files, packageHash: hash(JSON.stringify(files)),
+      loading: loaded.includes(entry.name) ? 'operator-attested-loaded' : 'installed-only' });
+  }
+  if (!skills.length) throw new Error('No skills found to snapshot');
+  if (loaded.some(name => !skills.some(s => s.name === name))) throw new Error('Attested loaded skill is absent from snapshot');
+  const at = now();
+  const snapshot = { id: crypto.randomUUID(), capturedAt: at, observedAt: at,
+    provenance: note, skillsRoot: root, skills,
+    warnings: skills.filter(s => !s.declaredVersion).map(s => `Unknown metadata.version: ${s.name}`) };
+  return snapshot;
+}
+export function captureConfiguration(file, options) {
+  const snapshot = snapshotConfiguration(options);
+  mutateRun(file, run => {
+    run.configurationHistory ??= [];
+    run.configurationHistory.push(snapshot);
+  });
+  return snapshot;
+}
+
+export function recordEnvironment(file, note) {
+  if (!note?.trim()) throw new Error('Environment note required');
+  return mutateRun(file, run => {
+    run.environmentHistory ??= [];
+    // Preserve legacy notes on the first new update, without relabeling their observation time.
+    if (run.environmentReview && !run.environmentHistory.length) run.environmentHistory.push({ ...run.environmentReview, legacy: true });
+    const event = { note, at: now() };
+    run.environmentHistory.push(event);
+    run.environmentReview = event;
+  });
+}
+
+export function attachConfiguration(file, { sessionKey, configurationId, note }) {
+  if (!note?.trim()) throw new Error('Configuration attribution requires a provenance note');
+  return mutateRun(file, run => {
+    const session = run.sessions.find(s => s.key === sessionKey);
+    if (!session) throw new Error('Unknown session key');
+    if (!run.configurationHistory?.some(c => c.id === configurationId)) throw new Error('Unknown configuration ID');
+    if (session.configurationId && session.configurationId !== configurationId) throw new Error('Session already has a different configuration; preserve history');
+    if (session.configurationId === configurationId) return;
+    session.configurationId = configurationId;
+    session.configurationAttribution = { note, at: now() };
+  });
+}

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

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const canonical = value => process.platform === 'win32' ? path.resolve(value).toLowerCase() : path.resolve(value);
+// Both CLIs relocate their home: a profile directory holds different logs than the default one.
+const defaultRoot = provider => provider === 'codex'
+  ? path.join(process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex'), 'sessions')
+  : path.join(process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), '.claude'), 'projects');
+function logFiles(root) {
+  const files = [];
+  (function visit(directory) {
+    if (!fs.existsSync(directory)) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.name.endsWith('.jsonl')) files.push(file);
+    }
+  })(root);
+  return files;
+}
+
+// Identity by content, never by recency: the marker is in that log because this session wrote it.
+export function whoami({ provider, project, nonce, root }) {
+  if (!['codex', 'claude'].includes(provider)) throw new Error('Invalid provider');
+  if (typeof nonce !== 'string' || !/^[A-Za-z0-9._:-]{8,100}$/.test(nonce)) throw new Error('Provide a --nonce of 8..100 plain characters');
+  root ??= defaultRoot(provider);
+  const matches = [];
+  for (const file of logFiles(root)) {
+    let text;
+    try { text = fs.readFileSync(file, 'utf8'); } catch { continue; }
+    if (!text.includes(nonce)) continue;
+    let sessionId = null, agentId = null, cwd = null;
+    for (const line of text.split(/\r?\n/)) {
+      let r;
+      try { r = JSON.parse(line); } catch { continue; }
+      const p = provider === 'codex' ? (r.type === 'session_meta' ? r.payload : null) : r;
+      const id = provider === 'codex' ? p?.id ?? p?.session_id : p?.sessionId ?? p?.session_id;
+      if (id) { sessionId ??= id; cwd ??= p?.cwd ?? null; agentId ??= p?.agentId ?? null; }
+    }
+    if (sessionId) matches.push({ provider, sessionId, agentId, log: path.resolve(file), cwd });
+  }
+  if (!matches.length) throw new Error(`No log contains the marker yet. The transcript is written after the call that emitted it: repeat this command in a later tool call. Searched: ${path.resolve(root)}`);
+  // --project is a declared constraint, so it narrows the candidates; it never picks among them.
+  const selected = project ? matches.filter(match => canonical(match.cwd ?? '') === canonical(project)) : matches;
+  if (!selected.length) throw new Error(`Marker found in ${matches.length} log(s), none with cwd ${path.resolve(project)}: ${matches.map(m => m.cwd ?? 'no recorded cwd').join(', ')}. Review before registering`);
+  if (selected.length > 1) throw new Error(`Marker found in ${selected.length} logs: ${selected.map(m => m.sessionId).join(', ')}. Use a fresh unique marker; no log is selected automatically.`);
+  return { ...selected[0], note: 'Identity established by a marker this session emitted, not by log recency. Register the phase explicitly.' };
+}
+
+export function discover({ provider, project, root, limit = 20 }) {
+  if (!['codex', 'claude'].includes(provider)) throw new Error('Invalid provider');
+  if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new Error('Limit must be 1..200');
+  root ??= defaultRoot(provider);
+  const candidates = [];
+  function visit(directory) {
+    if (!fs.existsSync(directory)) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.name.endsWith('.jsonl')) candidates.push({ file, modified: fs.statSync(file).mtimeMs });
+    }
+  }
+  visit(root);
+  candidates.sort((a, b) => b.modified - a.modified);
+  const found = [];
+  for (const { file, modified } of candidates) {
+    // Metadata prefix only. Never return message bodies or search by user prompt content.
+    const buffer = Buffer.alloc(256 * 1024), fd = fs.openSync(file, 'r');
+    let text;
+    try { text = buffer.subarray(0, fs.readSync(fd, buffer, 0, buffer.length, 0)).toString('utf8').replace(/^\uFEFF/, ''); }
+    finally { fs.closeSync(fd); }
+    for (const line of text.split(/\r?\n/)) {
+      let r;
+      try { r = JSON.parse(line); } catch { continue; }
+      const p = provider === 'codex' ? (r.type === 'session_meta' ? r.payload : null) : r;
+      const id = provider === 'codex' ? p?.id ?? p?.session_id : p?.sessionId ?? p?.session_id;
+      if (id && p?.cwd && canonical(p.cwd) === canonical(project)) {
+        found.push({ provider, sessionId: id, agentId: p.agentId ?? null, log: path.resolve(file), modifiedAt: new Date(modified).toISOString(), version: p.cli_version ?? p.version ?? null });
+        break;
+      }
+    }
+    if (found.length >= limit) break;
+  }
+  return { sessions: found, note: 'Metadata candidates only, never auto-selected. Confirm task ownership; logs without matching metadata in the prefix are not listed.' };
+}

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

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const [caseId, workspace] = process.argv.slice(2);
+const results = [];
+let orders, dashboard, exporter;
+try {
+  [orders, dashboard, exporter] = await Promise.all(['orders', 'dashboard', 'export'].map(name => import(pathToFileURL(path.join(workspace, 'src', `${name}.mjs`)))));
+} catch (error) {
+  console.log(JSON.stringify({ fatal: String(error.message).slice(0, 500) }));
+  process.exit(1);
+}
+const rows = Object.freeze([
+  Object.freeze({ id: 1, status: 'completed' }), Object.freeze({ id: 2, status: 'pending' }),
+  Object.freeze({ id: 3, status: 'completed' }), Object.freeze({ id: 4, status: 'cancelled' })
+]);
+const expected = { total: 4, byStatus: { pending: 1, completed: 2, cancelled: 1 } };
+function check(id, fn) {
+  try { fn(); results.push({ id, status: 'pass', observation: 'Fixed assertions passed.' }); }
+  catch (e) { results.push({ id, status: 'fail', observation: String(e.message).slice(0, 1200) }); }
+}
+if (caseId === 'order-filter') {
+  check('filter', () => {
+    for (const status of ['pending', 'completed', 'cancelled']) {
+      assert.deepEqual(orders.filterOrders(rows, status), rows.filter(r => r.status === status));
+    }
+  });
+  check('consumers', () => {
+    for (const status of ['pending', 'completed', 'cancelled']) {
+      const wanted = rows.filter(r => r.status === status);
+      assert.deepEqual(dashboard.dashboardOrders(rows, status), wanted);
+      assert.deepEqual(exporter.exportOrders(rows, status), wanted);
+    }
+  });
+} else if (caseId === 'order-summary') {
+  check('summary', () => {
+    assert.deepEqual(orders.summarizeOrders(rows), expected);
+    assert.deepEqual(orders.summarizeOrders([]), { total: 0, byStatus: { pending: 0, completed: 0, cancelled: 0 } });
+    assert.deepEqual(orders.summarizeOrders([rows[0]]), { total: 1, byStatus: { pending: 0, completed: 1, cancelled: 0 } });
+  });
+  check('consumers', () => {
+    for (const f of [dashboard.dashboardSummary, exporter.exportSummary]) {
+      assert.deepEqual(f(rows), expected);
+      assert.deepEqual(f([]), { total: 0, byStatus: { pending: 0, completed: 0, cancelled: 0 } });
+    }
+  });
+} else throw new Error('Unknown case');
+check('regression', () => {
+  for (const f of [orders.filterOrders, dashboard.dashboardOrders, exporter.exportOrders]) {
+    assert.deepEqual(f(rows, 'all'), rows);
+    assert.deepEqual(f([], 'completed'), []);
+    assert.deepEqual(f(rows, 'absent'), []);
+    if (caseId === 'order-summary') assert.deepEqual(f(rows, 'completed'), [rows[0], rows[2]]);
+  }
+  assert.deepEqual(rows.map(r => r.id), [1, 2, 3, 4]);
+});
+console.log(JSON.stringify({ results }));

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

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const hash = data => crypto.createHash('sha256').update(data).digest('hex');
+export const readJSON = file => JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+export const now = () => new Date().toISOString();
+export function requireValue(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`Required: ${name}`);
+  return value;
+}
+export function safeId(value) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$/.test(value ?? '')) throw new Error('Invalid ID');
+  return value;
+}
+export function inside(root, relative) {
+  const resolved = path.resolve(root, relative);
+  const rel = path.relative(path.resolve(root), resolved);
+  if (rel === '' || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    throw new Error(`Path must be strictly inside target: ${relative}`);
+  }
+  return resolved;
+}
+export function rejectSymlinkPath(target) {
+  let current = path.resolve(target);
+  for (;;) {
+    let stat;
+    try { stat = fs.lstatSync(current); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    if (stat?.isSymbolicLink()) throw new Error(`Symlink target refused: ${current}`);
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+export function writeJSON(file, data) {
+  rejectSymlinkPath(file);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(data, null, 2)}\n`, { flag: 'wx' });
+  try { fs.renameSync(temporary, file); } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
+}
+export function newDirectory(target) {
+  rejectSymlinkPath(target);
+  if (fs.existsSync(target)) throw new Error(`Target already exists: ${target}`);
+  fs.mkdirSync(target, { recursive: true });
+}
+export function writeNew(file, content) {
+  rejectSymlinkPath(file);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, { flag: 'wx' });
+}
+export function listFiles(root, prefix = '') {
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true }).flatMap(entry => {
+    if (entry.isSymbolicLink()) throw new Error(`Symlink source refused: ${entry.name}`);
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    return entry.isDirectory() ? listFiles(path.join(root, entry.name), relative) : [relative];
+  }).sort();
+}
+export function treeHash(root) {
+  return hash(JSON.stringify(listFiles(root).map(relative => [relative, hash(fs.readFileSync(path.join(root, relative)))])));
+}
+export function loadRun(file) {
+  const run = readJSON(file);
+  if (run.schemaVersion !== 1 || !Array.isArray(run.sessions) || !Array.isArray(run.criteria)) {
+    throw new Error('Unsupported run manifest');
+  }
+  return run;
+}
+export function mutateRun(file, fn) {
+  // One writer per manifest; fail explicitly rather than lose concurrent updates.
+  rejectSymlinkPath(file);
+  const lock = `${file}.lock`;
+  const fd = fs.openSync(lock, 'wx');
+  try {
+    const run = loadRun(file);
+    fn(run);
+    run.updatedAt = now();
+    writeJSON(file, run);
+    return run;
+  } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
+}

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

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CASES, handoff, smoke } from './cases.mjs';
+import { createRun } from './runs.mjs';
+import { hash, listFiles, readJSON, inside, writeJSON, writeNew, mutateRun } from './io.mjs';
+
+// The frozen baseline keeps the original skill names; candidates use the current prefixed names.
+const baselineNames = ['interactive-spec-definition', 'handoff-implementation', 'visual-check'];
+const candidateNames = ['denisco-interactive-spec-definition', 'denisco-handoff-implementation', 'denisco-visual-check'];
+export function prepare({ out, caseId, variant, provider, baseline, sourceRoot }) {
+  const definition = CASES[caseId];
+  if (!definition) throw new Error('Case must be order-filter or order-summary');
+  if (!['baseline', 'candidate'].includes(variant)) throw new Error('Variant must be baseline or candidate');
+  if (!['codex', 'claude'].includes(provider)) throw new Error('Choose the provider that will run this case');
+  const files = [];
+  if (variant === 'baseline') {
+    if (!baseline) throw new Error('Explicit --baseline manifest is required');
+    const snapshot = readJSON(baseline);
+    if (snapshot.schemaVersion !== 1 || snapshot.id !== 'original-v1') throw new Error('Invalid baseline');
+    for (const file of snapshot.files) {
+      const content = Buffer.from(file.base64, 'base64');
+      if (hash(content) !== file.sha256) throw new Error(`Baseline integrity failure: ${file.path}`);
+      if (!baselineNames.includes(file.path.split('/')[0])) throw new Error('Unexpected baseline skill');
+      inside(out, file.path);
+      files.push({ path: file.path, content });
+    }
+  } else {
+    const supplied = sourceRoot ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+    const nested = path.join(supplied, 'skills');
+    const root = fs.existsSync(nested) && fs.statSync(nested).isDirectory() && !fs.existsSync(path.join(nested, 'SKILL.md')) ? nested : supplied;
+    for (const name of candidateNames) {
+      if (!fs.existsSync(path.join(root, name, 'SKILL.md'))) throw new Error(`Missing benchmark skill: ${name}`);
+      for (const file of listFiles(path.join(root, name))) {
+        files.push({ path: `${name}/${file}`, content: fs.readFileSync(path.join(root, name, file)) });
+      }
+    }
+  }
+  const workspace = path.resolve(out, 'workspace');
+  const criteria = definition.criteria;
+  createRun({ out, task: caseId, project: workspace, variant, criteria });
+  const appFiles = { ...definition.files, 'smoke.mjs': smoke, 'HANDOFF.md': handoff(caseId),
+    'package.json': '{"private":true,"type":"module","scripts":{"test":"node smoke.mjs"}}\n',
+    'AGENTS.md': '# Benchmark workspace\n\nImplement the decided HANDOFF.md. Run node smoke.mjs and focused tests.\nOnly modify src files, add focused tests, and write PLAN.md/STATE.md or handoff reports.\nDo not inspect external evaluators/reference solutions, alter the handoff, installed skills or this file.\nThe operator runs fixed acceptance checks separately. No browser, login or external services.\nFollow the supplied handoff implementation skill and preserve its session workflow.\n',
+    'CLAUDE.md': 'Read AGENTS.md and HANDOFF.md. The benchmark contract applies to every session.\n' };
+  for (const [relative, content] of Object.entries(appFiles)) writeNew(inside(workspace, relative), content);
+  const skillsDir = provider === 'codex' ? '.agents/skills' : '.claude/skills';
+  for (const file of files) writeNew(inside(workspace, `${skillsDir}/${file.path}`), file.content);
+  const protectedFiles = Object.fromEntries(Object.entries(appFiles).filter(([p]) => !p.startsWith('src/')).map(([p, text]) => [p, hash(text)]));
+  for (const file of files) protectedFiles[`${skillsDir}/${file.path}`] = hash(file.content);
+  const caseInputHash = hash(JSON.stringify({ caseId, criteria, appFiles }));
+  mutateRun(path.join(out, 'run.json'), run => {
+    run.caseId = caseId; run.caseInputHash = caseInputHash;
+    run.skillSnapshot = Object.fromEntries(files.map(f => [f.path, hash(f.content)]));
+    run.protectedFiles = protectedFiles;
+    run.preparedProvider = provider;
+  });
+  const implementationSkill = variant === 'baseline' ? 'handoff-implementation' : 'denisco-handoff-implementation';
+  const prompt = `Use ${implementationSkill} with HANDOFF.md. Follow its planning and session-split procedure. The product behavior is decided. Do not inspect anything outside this workspace, especially evaluator or reference solutions. If the workflow blocks, report it instead of silently replacing its procedure. Record actual loaded skill paths, model, effort and external instructions for the operator.\n`;
+  writeNew(path.join(out, 'PROMPT.md'), prompt);
+  writeNew(path.join(out, 'OPERATOR.md'), `# Operatore\n\nCaso ${caseId}; variante ${variant}; CLI ${provider}.\n\n1. Esegui git init in workspace e verifica con git rev-parse --show-toplevel che sia la radice del progetto. Poi avvia ${provider} lì.\n2. Verifica le skill effettivamente caricate e annota modello, effort, configurazioni globali e memoria. Un conflitto di skill rende la prova contaminata.\n3. Incolla PROMPT.md. Conferma soltanto il piano di sessioni previsto; segui i prompt successivi. Registra interventi e blocchi.\n4. Registra ogni sessione con bench.mjs session, poi collect dopo la chiusura. Includi subagenti attribuibili e conferma la copertura solo dopo revisione.\n5. Esegui bench.mjs evaluate --run <run.json> e report.\n\nIl verificatore si trova nel toolkit, fuori da workspace. Questa separazione è procedurale, non una sandbox di sicurezza. Non usare prove con ispezione del verificatore per conclusioni controllate.\nNon è stata avviata alcuna sessione con modelli.\n`);
+  return { run: path.resolve(out, 'run.json'), workspace, prompt: path.resolve(out, 'PROMPT.md'), variant, provider };
+}
+export function checkProtected(run) {
+  return Object.entries(run.protectedFiles ?? {}).filter(([relative, expected]) => {
+    const file = inside(run.project, relative);
+    return !fs.existsSync(file) || hash(fs.readFileSync(file)) !== expected;
+  }).map(([relative]) => relative);
+}

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

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { hash, treeHash, now, newDirectory, writeJSON, safeId, loadRun, mutateRun, rejectSymlinkPath, inside } from './io.mjs';
+import { importUsage } from './usage.mjs';
+// Baseline runs load the original name; current packages use the prefixed one.
+const visualCheckNames = ['visual-check', 'denisco-visual-check'];
+
+export const phases = ['exploration', 'specification', 'planning', 'implementation', 'verification', 'correction'];
+export function createRun({ out, task, project, variant, criteria }) {
+  safeId(task); safeId(variant);
+  if (!Array.isArray(criteria) || !criteria.length || criteria.some(c => !c.id || !c.expectation) || new Set(criteria.map(c => c.id)).size !== criteria.length) throw new Error('Provide nonempty unique criteria with id and expectation');
+  criteria.forEach(c => safeId(c.id));
+  if (!criteria.some(c => c.required !== false)) throw new Error('At least one required acceptance criterion is needed');
+  newDirectory(out);
+  const run = { schemaVersion: 1, id: path.basename(path.resolve(out)), task, project: path.resolve(project), variant,
+    createdAt: now(), updatedAt: now(), criteria: criteria.map(c => ({ id: c.id, expectation: String(c.expectation), required: c.required !== false })),
+    sessions: [], visualChecks: [], evidence: [], history: [], interventions: [], review: { status: 'pending', note: '' }, environmentReview: null };
+  writeJSON(path.join(out, 'run.json'), run);
+  return run;
+}
+export function startVisualCheck(file, { id, block, criteria, executor = 'subagent', principalSession, at } = {}) {
+  // Omitted executor preserves the legacy CLI contract. New workflow calls select principal explicitly.
+  if (!['principal', 'subagent'].includes(executor)) throw new Error('Invalid visual check executor');
+  safeId(id); safeId(block); if (!Array.isArray(criteria) || !criteria.length) throw new Error('Visual check criteria are required');
+  criteria.forEach(safeId); if (principalSession && typeof principalSession !== 'string') throw new Error('Invalid principal session');
+  return mutateRun(file, run => {
+    if (run.visualChecks?.some(check => check.id === id)) throw new Error('Visual check ID already used; create a new attempt ID');
+    if (criteria.some(criterion => !run.criteria.some(c => c.id === criterion))) throw new Error('Unknown visual check criterion');
+    run.visualChecks ??= [];
+    run.visualChecks.push({ id, block, criteria, executor, principalSession: principalSession ?? null,
+      startedAt: at ?? now(), finishedAt: null, status: 'started', skillLoaded: null, sessionKey: null, results: [], evidence: [] });
+  });
+}
+
+export function finishVisualCheck(file, { id, sessionKey, skillLoaded, results = [], evidence = [], at } = {}) {
+  if (typeof skillLoaded !== 'boolean') throw new Error('Visual check skillLoaded must be true or false');
+  if (!Array.isArray(results) || !Array.isArray(evidence)) throw new Error('Visual check results and evidence must be arrays');
+  return mutateRun(file, run => {
+    const check = run.visualChecks?.find(candidate => candidate.id === id);
+    if (!check) throw new Error('Unknown visual check ID');
+    if (check.status === 'finished') throw new Error('Visual check already finished');
+    const session = sessionKey && run.sessions.find(candidate => candidate.key === sessionKey);
+    if (!session) throw new Error('Visual check session is not registered');
+    const executor = check.executor ?? 'subagent';
+    if (executor === 'subagent') {
+      if (!session.parent) throw new Error('Visual check must be executed by a registered child session');
+      if (check.principalSession && session.parent !== check.principalSession) throw new Error('Visual check child belongs to a different principal');
+    } else if (executor === 'principal') {
+      if (session.parent || session.agentId) throw new Error('Principal visual check requires a top-level session');
+      if (check.principalSession && session.key !== check.principalSession) throw new Error('Visual check session differs from the assigned principal');
+    } else throw new Error('Invalid visual check executor');
+    const invocation = session.metrics.skillInvocations?.some(entry => visualCheckNames.includes(entry.skill))
+      || session.metrics.commandInvocations?.some(entry => visualCheckNames.includes(entry.command));
+    if (skillLoaded && !invocation) throw new Error('Visual check loading is not present in the registered executor log');
+    for (const result of results) if (!result?.criterion || !check.criteria.includes(result.criterion) || !['pass', 'fail', 'not-run'].includes(result.status)) throw new Error('Invalid visual check criterion result');
+    for (const artifact of evidence) if (typeof artifact !== 'string' || !fs.existsSync(artifact) || !fs.statSync(artifact).isFile()) throw new Error('Visual check evidence must be an existing file');
+    check.finishedAt = at ?? now(); check.status = 'finished'; check.skillLoaded = skillLoaded; check.sessionKey = sessionKey;
+    check.results = results.map(result => ({ criterion: result.criterion, status: result.status, observation: String(result.observation ?? '') }));
+    check.evidence = evidence.map(artifact => ({ path: path.resolve(artifact), sha256: hash(fs.readFileSync(artifact)) }));
+  });
+}
+export function registerSession(file, { provider, sessionId, agentId, log, phase, from, to, parent, parentEvidence, coverageConfirmed = false, configurationId, configurationSnapshot }) {
+  if (configurationId && configurationSnapshot) throw new Error('Choose an existing configuration or a new snapshot');
+  if (!['codex', 'claude'].includes(provider) || !phases.includes(phase)) throw new Error('Invalid provider or phase');
+  safeId(sessionId);
+  if (agentId) safeId(agentId);
+  const key = `${provider}:${sessionId}${agentId ? ':' + agentId : ''}`;
+  const parsed = importUsage(log, provider, { sessionId, agentId, from, to });
+  return mutateRun(file, run => {
+    if (run.sessions.some(s => s.key === key)) throw new Error('Session already registered; collect again to refresh');
+    if (parent && !run.sessions.some(s => s.key === parent)) throw new Error('Register parent first, using provider:session-id');
+    if (parent && !parentEvidence?.trim()) throw new Error('Parent attribution requires --parent-evidence describing the verified native relationship');
+    if (agentId && !parent) throw new Error('An agent log requires an explicitly attributed parent');
+    if (configurationId && !run.configurationHistory?.some(c => c.id === configurationId)) throw new Error('Unknown configuration ID');
+    if (configurationSnapshot) {
+      if (!configurationSnapshot.id || !configurationSnapshot.skills?.length || run.configurationHistory?.some(c => c.id === configurationSnapshot.id)) throw new Error('Invalid or duplicate configuration snapshot');
+      run.configurationHistory ??= [];
+      run.configurationHistory.push(configurationSnapshot);
+      configurationId = configurationSnapshot.id;
+    }
+    run.sessions.push({ key, provider, sessionId, agentId: agentId ?? null, log: path.resolve(log), phase, from: from ?? null, to: to ?? null,
+      parent: parent ?? null, parentEvidence: parentEvidence ?? null, coverageConfirmed, metrics: parsed, registeredAt: now(),
+      ...(configurationId ? { configurationId } : {}) });
+  });
+}
+export function collect(file, { coverageConfirmed = false } = {}) {
+  return mutateRun(file, run => {
+    // Build everything before assignment: an invalid log does not partially change the manifest.
+    run.sessions = run.sessions.map(s => ({ ...s, coverageConfirmed: coverageConfirmed || s.coverageConfirmed, metrics: importUsage(s.log, s.provider, s), collectedAt: now() }));
+  });
+}
+export function recordEvidence(file, { criterion, status, observation, evidence }) {
+  if (!['pass', 'fail', 'not-run'].includes(status) || !observation?.trim()) throw new Error('Provide status and actual observation');
+  if (status !== 'not-run' && (!evidence || !fs.statSync(evidence).isFile())) throw new Error('A real evidence file is required');
+  return mutateRun(file, run => {
+    if (!run.criteria.some(c => c.id === criterion)) throw new Error('Unknown criterion');
+    run.evidence.push({ criterion, status, observation, path: evidence ? path.resolve(evidence) : null,
+      sha256: evidence ? hash(fs.readFileSync(evidence)) : null, at: now(), source: 'operator' });
+  });
+}
+export function evaluate(file) {
+  const run = loadRun(file);
+  if (!run.caseId) throw new Error('Generic tasks use result with actual evidence; no inferred evaluator');
+  const worker = fileURLToPath(new URL('./eval-worker.mjs', import.meta.url));
+  const implementationHash = treeHash(path.join(run.project, 'src'));
+  const workerEnv = Object.fromEntries(['PATH', 'Path', 'SystemRoot', 'SYSTEMROOT', 'TEMP', 'TMP', 'TMPDIR'].filter(k => process.env[k]).map(k => [k, process.env[k]]));
+  const result = spawnSync(process.execPath, [worker, run.caseId, run.project], {
+    cwd: run.project, encoding: 'utf8', timeout: 15000, maxBuffer: 1024 * 1024,
+    env: workerEnv, windowsHide: true
+  });
+  let output;
+  try { output = JSON.parse(result.stdout?.trim().split(/\r?\n/).at(-1) ?? '{}'); } catch { output = {}; }
+  const valid = result.status === 0 && Array.isArray(output.results) && run.criteria.every(c => output.results.some(r => r.id === c.id && ['pass', 'fail'].includes(r.status)));
+  const results = valid ? output.results : run.criteria.map(c => ({ id: c.id, status: 'fail', observation: result.error?.message ?? output.fatal ?? 'Evaluator failed or timed out.' }));
+  const artifact = path.join(path.dirname(file), 'evidence', `${Date.now()}-${process.hrtime.bigint()}.json`);
+  writeJSON(artifact, { schemaVersion: 1, caseId: run.caseId, at: now(), evaluatorHash: hash(fs.readFileSync(worker)),
+    exitCode: result.status, results, stderr: (result.stderr ?? '').slice(0, 2000) });
+  mutateRun(file, current => {
+    for (const r of results) current.evidence.push({ criterion: r.id, status: r.status, observation: r.observation,
+      path: artifact, sha256: hash(fs.readFileSync(artifact)), implementationHash, at: now(), source: 'fixed-evaluator' });
+  });
+  return { passed: results.every(r => r.status === 'pass'), results, artifact };
+}
+
+// Usage is final only while the imported log still hashes to what the last import recorded.
+export function usageState(session) {
+  if (!fs.existsSync(session.log)) return 'unavailable';
+  return hash(fs.readFileSync(session.log)) === session.metrics.sourceHash ? 'final' : 'stale';
+}
+
+export function summarize(run) {
+  const latest = new Map();
+  for (const e of run.evidence) latest.set(e.criterion, e);
+  const required = run.criteria.filter(c => c.required !== false);
+  const current = required.map(c => latest.get(c.id));
+  const evidenceChanged = current.some(e => e && ['pass', 'fail'].includes(e.status) && (!e.path || !e.sha256 || !fs.existsSync(e.path) || !fs.statSync(e.path).isFile() || hash(fs.readFileSync(e.path)) !== e.sha256));
+  const implementationChanged = run.caseId && current.some(e => e?.implementationHash && e.implementationHash !== treeHash(path.join(run.project, 'src')));
+  const protectedChanges = Object.entries(run.protectedFiles ?? {}).filter(([relative, expected]) => {
+    const file = inside(run.project, relative);
+    return !fs.existsSync(file) || hash(fs.readFileSync(file)) !== expected;
+  }).map(([relative]) => relative);
+  const lastReopen = run.history.filter(e => e.type === 'reopened').at(-1);
+  const fresh = !lastReopen || (Number.isInteger(lastReopen.evidenceCount)
+    ? required.every(c => run.evidence.slice(lastReopen.evidenceCount).some(e => e.criterion === c.id))
+    : current.every(e => e && e.at > lastReopen.at));
+  const quality = protectedChanges.length ? 'contaminated' : evidenceChanged ? 'evidence-changed' : implementationChanged ? 'implementation-changed' : !fresh ? 'reopened' : required.length && current.every(e => e?.status === 'pass') ? 'verified' : current.some(e => e?.status === 'fail') ? 'failed' : current.some(e => e?.status === 'not-run') ? 'blocked' : 'unverified';
+  const groups = new Map(), warnings = [], requestKeys = new Set();
+  for (const s of run.sessions) {
+    for (const key of s.metrics.requestKeys) {
+      if (requestKeys.has(key)) warnings.push('Request occurs in multiple registered logs: aggregates may double-count.');
+      requestKeys.add(key);
+    }
+    const groupKey = `${s.provider}/${s.phase}`;
+    if (!groups.has(groupKey)) groups.set(groupKey, { provider: s.provider, phase: s.phase, sessions: 0,
+      input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 });
+    const group = groups.get(groupKey); group.sessions++;
+    for (const k of ['input', 'output', 'cacheRead', 'cacheWrite', 'reasoning', 'total']) {
+      const value = s.metrics.usage[k]; group[k] = group[k] === null || value === null ? null : group[k] + value;
+    }
+    const notes = s.metrics.warnings.filter(w => !s.coverageConfirmed || !w.startsWith('Full-history import:'));
+    warnings.push(...notes.map(w => `${s.key}: ${w}`));
+    if (!s.coverageConfirmed) warnings.push(`${s.key}: scope/subagent completeness not confirmed.`);
+    const freshness = usageState(s);
+    if (freshness === 'stale') warnings.push(`${s.key}: log changed after the last import; run collect before using these totals.`);
+    if (freshness === 'unavailable') warnings.push(`${s.key}: log is unavailable; totals cannot be refreshed.`);
+    if (!s.metrics.models.length || !s.metrics.versions.length) warnings.push(`${s.key}: CLI version or model is unknown.`);
+    if (run.configurationHistory?.length && !s.configurationId) warnings.push(`${s.key}: skill configuration not attributed; do not infer it from the latest snapshot.`);
+    if (s.configurationId && !run.configurationHistory?.some(c => c.id === s.configurationId)) warnings.push(`${s.key}: referenced configuration is missing.`);
+  }
+  if (!run.sessions.length) warnings.push('No sessions measured.');
+  for (const attempt of run.registrationAttempts ?? []) {
+    if (attempt.status !== 'registered') warnings.push(`Session registration pending (${attempt.phase}): ${attempt.reason ?? 'Identity unavailable'}. Agent record: ${attempt.ticket}`);
+  }
+  if (!run.environmentReview) warnings.push('Loaded skills, settings and environment not reviewed.');
+  if (protectedChanges.length) warnings.push(`Protected benchmark files changed: ${protectedChanges.join(', ')}`);
+  const visualChecks = (run.visualChecks ?? []).map(check => ({ ...check, executor: check.executor ?? 'subagent',
+    durationMs: check.finishedAt ? Math.max(0, Date.parse(check.finishedAt) - Date.parse(check.startedAt)) : null }));
+  const visualWarnings = visualChecks.flatMap(check => [
+    ...(check.status !== 'finished' ? [`${check.id}: visual check is incomplete.`] : []),
+    ...(check.status === 'finished' && !check.skillLoaded ? [`${check.id}: denisco-visual-check loading was not confirmed.`] : []),
+    ...(check.status === 'finished' && !check.sessionKey ? [`${check.id}: executor session is missing.`] : [])]);
+  return { schemaVersion: 1, runId: run.id, task: run.task, variant: run.variant, quality, review: run.review,
+    passed: current.filter(e => e?.status === 'pass').length, required: required.length,
+    usage: run.sessions.map(s => ({ key: s.key, phase: s.phase, state: usageState(s), collectedAt: s.collectedAt ?? null, total: s.metrics.usage.total })),
+    phases: [...groups.values()], sessions: run.sessions.length, interventions: run.interventions.length,
+    warnings: [...new Set([...warnings, ...visualWarnings])], coverage: warnings.length || visualWarnings.length ? 'partial-or-unreviewed' : 'reviewed',
+    visualChecks,
+    configurations: run.sessions.map(s => ({ key: s.key, provider: s.provider, phase: s.phase, models: s.metrics.models,
+      versions: s.metrics.versions, efforts: s.metrics.efforts, observedDurationMs: s.metrics.observedDurationMs,
+      configurationId: s.configurationId ?? null })),
+    configurationHistory: run.configurationHistory ?? [], environmentHistory: run.environmentHistory ?? [],
+    environmentReview: run.environmentReview, caseInputHash: run.caseInputHash ?? null };
+}
+const escape = text => String(text).replaceAll('|', '\\|').replaceAll('\n', ' ');
+export function report(file) {
+  const run = loadRun(file), summary = summarize(run);
+  const visualSection = summary.visualChecks.length
+    ? `\n## Verifiche visuali\n\n${summary.visualChecks.map(check => `- ${escape(check.id)}: ${check.status}; esecutore: ${check.executor}; skill caricata: ${check.skillLoaded ?? 'n/d'}; sessione: ${check.sessionKey ?? 'n/d'}; durata ms: ${check.durationMs ?? 'n/d'}`).join('\n')}\n`
+    : '';
+  const md = `# Run ${escape(run.id)}\n\nTask: ${escape(run.task)}. Variante: ${escape(run.variant)}.\n\nEsito: **${summary.quality}** (${summary.passed}/${summary.required}). Accettazione utente: ${run.review.status}.\n\n| Provider | Fase | Sessioni | Input totale | Cache letta | Cache scritta | Output | Totale |\n|---|---|---:|---:|---:|---:|---:|---:|\n${summary.phases.map(g => `| ${g.provider} | ${g.phase} | ${g.sessions} | ${g.input ?? 'n/d'} | ${g.cacheRead ?? 'n/d'} | ${g.cacheWrite ?? 'n/d'} | ${g.output ?? 'n/d'} | ${g.total ?? 'n/d'} |`).join('\n')}\n\n${visualSection}\nCache e reasoning sono dettagli, non quantità da sommare nuovamente al totale.\nEsplorazione separata; nessun costo monetario stimato. Durate osservate non equivalgono a tempo attivo.\n\n## Copertura\n\n${summary.warnings.length ? summary.warnings.map(w => `- ${escape(w)}`).join('\n') : 'Dati e perimetro revisionati.'}\n\n## Evidenze\n\n${run.criteria.map(c => { const e = run.evidence.filter(e => e.criterion === c.id).at(-1); return `- ${escape(c.id)}: ${e?.status ?? 'not-run'} — ${escape(e?.observation ?? c.expectation)}${e?.path ? ` (${escape(e.path)})` : ''}`; }).join('\n')}\n`;
+  const accounting = `
+## Contabilita dei consumi
+
+${summary.usage.map(u => `- ${escape(u.key)} (${escape(u.phase)}): ${u.state}; ultimo collect: ${u.collectedAt ?? 'mai dopo la registrazione'}; totale ${u.total ?? 'n/d'}`).join('\n')}
+
+Finale significa che il log non e' cambiato dopo l'ultimo import. Stale richiede collect prima di
+usare questi totali: la sessione successiva lo esegue con open, altrimenti spetta all'operatore.
+`;
+  writeJSON(path.join(path.dirname(file), 'report.json'), summary);
+  const markdownPath = path.join(path.dirname(file), 'report.md');
+  rejectSymlinkPath(markdownPath);
+  const configurations = `\n## Configurazioni delle skill\n\n${summary.configurations.map(c => `- ${escape(c.key)}: ${c.configurationId ?? 'non attribuita'}`).join('\n')}\n\n${summary.configurationHistory.map(c => `- ${escape(c.id)}: osservata ${escape(c.observedAt)}, acquisita ${escape(c.capturedAt)}. ${escape(c.provenance)}\n${c.skills.map(s => `  - ${escape(s.name)}: ${s.declaredVersion ?? 'versione sconosciuta'}; ${escape(s.loading)}; hash ${s.packageHash}`).join('\n')}`).join('\n')}\n\nInstallata non significa caricata. Le attestazioni richiedono riscontri della sessione.\n`;
+  fs.writeFileSync(markdownPath, md + accounting + configurations);
+  return summary;
+}
+export function compare(files) {
+  const rows = files.map(f => summarize(loadRun(f)));
+  const notes = ['Descriptive pilot only. Quality precedes consumption; failed and blocked runs are included.'];
+  const first = rows[0];
+  for (const row of rows.slice(1)) {
+    if (row.task !== first.task || !row.caseInputHash || row.caseInputHash !== first.caseInputHash) notes.push('Inputs not matched: no controlled efficiency conclusion.');
+    const configuration = r => JSON.stringify([...new Set(r.configurations.map(c => JSON.stringify({ provider: c.provider, models: c.models, versions: c.versions, efforts: c.efforts })))].sort());
+    if (configuration(row) !== configuration(first)) notes.push('Provider/model/version/effort differs: comparison is confounded.');
+    const packages = r => [...new Set(r.configurationHistory.map(c => JSON.stringify(c.skills.map(s => [s.name, s.packageHash]).sort())))].sort();
+    if (JSON.stringify(packages(row)) !== JSON.stringify(packages(first))) notes.push('Recorded skill snapshots differ; inspect configuration attribution before interpreting the comparison.');
+    if (row.configurations.some(c => first.configurations.some(other => other.key === c.key))) notes.push('Native session reused across comparison runs: check attribution before drawing conclusions.');
+  }
+  if (rows.some(r => r.coverage !== 'reviewed')) notes.push('Some consumption or environment coverage is incomplete/unreviewed.');
+  return { rows, counts: { runs: rows.length, verified: rows.filter(r => r.quality === 'verified').length,
+    failed: rows.filter(r => r.quality === 'failed').length, blocked: rows.filter(r => r.quality === 'blocked').length,
+    unverifiedOrInvalidated: rows.filter(r => !['verified', 'failed', 'blocked'].includes(r.quality)).length,
+    userAccepted: rows.filter(r => r.review.status === 'accepted').length }, notes: [...new Set(notes)] };
+}