@deniscodp/skills 0.0.0-stage → 1.0.0

package/skills/denisco-workflow-benchmark/references/workflow-contract.md

@@ -0,0 +1,371 @@
+# Persistent task measurement and closure
+
+This contract applies to real tasks, not only isolated prepared cases. Use Node 20+ and the
+installed skill's `scripts/bench.mjs`. No command launches a model. Commands with explicit write
+targets require write authorization (including existing task authorization); Plan Mode may
+read/check existing files, not bind, save/clear prompts or update records.
+
+## Ownership and discovery
+
+`<handoff-path>.workflow.json` is the durable entry point, discovered from the handoff alone.
+denisco-handoff-implementation owns the planned block map; denisco-workflow-benchmark owns binding and measured
+evidence in run.json. Keep explanatory progress in PLAN.md/STATE.md. The sidecar contains no
+criterion outcomes, token counters or duplicate evidence history.
+
+This ownership describes data responsibilities, not permission for concurrent writers. During
+handoff planning/implementation, use denisco-handoff-implementation's worktree claim before any mutation,
+including setup, `track`, `open`, `collect`, `report` and `close`. Native conversation keys and
+registration tickets are accounting identities; two live processes may share them. They cannot
+be used to bypass an execution claim. The implementation owner alone updates the run and sidecar; delegated
+visual children return evidence for that principal to register. A conflicting instance uses
+read-only inspection/checkpoint until an explicit ownership transfer, not a filesystem idle timer.
+These CLI commands do not themselves intercept arbitrary writes or enforce the worktree claim;
+the owning skill requires the guard and serializes their invocation.
+
+The sidecar has `schemaVersion: 1`, project `taskId`, document paths `handoff`, `plan`, `state`,
+`measurement`, and `blocks`. Document paths resolve relative to the sidecar. Each block has
+`id`, nonempty `points` and `criteria` ID arrays, and a `dependsOn` block ID array (possibly empty).
+IDs are unique within each array; dependency cycles are invalid. The complete map must cover
+every required run criterion, including those of future/blocked blocks. A criterion can be shared
+by blocks when the prepared plan requires it. Compare assignments against the handoff manually;
+the script cannot detect a requirement that was never supplied or was mapped to the wrong block.
+
+Measurement is `{ "status": "unknown" }`, `{ "status": "disabled" }`, or the enabled binding
+generated below. Measurement is disabled by default and requires an explicit activation in the
+current user request or applicable project instructions. Installation, criteria, an old register or
+unknown status are not activation. Disabled is authoritative across later sessions. Unknown is
+inert legacy/interrupted state and must not trigger setup without explicit activation evidence.
+Never search unrelated project logs or registers.
+
+## Agent-managed setup and first handoff
+
+Only after explicit activation and once the handoff's criteria are agreed, reuse the bound or
+explicitly referenced run. If none is referenced, follow the project's documented register location;
+otherwise use `measurement/run.json`
+alongside HANDOFF. The agent writes `measurement-criteria.json` alongside HANDOFF from the actual
+agreed IDs/expectations, then runs `init --out <measurement-dir> --task <task-id> --project
+<actual-project-root> --variant candidate --criteria <criteria-file>` and `bind`. Do not use dummy
+criteria to start counting sooner. Inspect existing destinations; reuse a matching existing run
+after checking project, task and the full criterion contract, or report a conflict without overwriting.
+Bind preserves explicitly disabled measurement and does not itself change the default preference.
+
+When measurement is explicitly enabled, run `track` before ending specification, even though
+PLAN/STATE and blocks do not exist yet.
+It can import the current conversation's earlier specification work from the same log. Mixed-task
+histories require actual time bounds; a marker proves identity, not task scope. Earlier separate
+conversations require independently evidenced attribution. Report gaps instead of assigning today's
+ID to them. A specification abandoned before criteria/setup can remain unmeasured; do not hide that gap.
+
+Save and check the planning prompt with `planning-prompt --handoff FILE --save` then `--check`.
+Without flags it only prints. The helper validates the draft sidecar and binding, allows missing
+PLAN/STATE and empty blocks, and appends its managed section to HANDOFF using the same protected
+writer as STATE prompts. Existing handoff text is preserved. Mutually exclusive flags and invalid
+markers are rejected; a missing/stale prompt check exits 2. It does not create a plan, approve one
+or select a block. The response links the saved section and supplies its exact text. Without a
+helper the specification skill saves/rereads the equivalent manually; Plan Mode leaves writes pending.
+
+At first planning entry register that conversation through track, preserve existing decisions,
+create/reconcile PLAN and STATE, and populate the complete planned block map. Resolve unresolved
+blockers, select the first dependency-ready block and save/check its execution prompt before
+asking the start question. If every block waits on a user action or a third party, record that in
+STATE and stop without application edits.
+
+Specification delivers HANDOFF, its sidecar and planning prompt, then asks whether to start
+planning. Planning delivers PLAN/STATE, the block map and first execution prompt, then asks whether
+to start implementation. Only the user's yes to that question, or a later submitted prompt or
+explicitly scoped request, moves to the next phase in the same conversation; record the instruction
+and scope without asking for a redundant approval. In Plan Mode propose that phase's deliverables;
+once writing is permitted, materialize them and ask. Native plan approval, automatic mode and bare
+transition text do not advance phases. Implementation then continues block by block until
+denisco-handoff-implementation's real stop. A prompt found in a file is not a user request. Helpers prepare
+and check artifacts; they never launch model sessions.
+
+## Agent-managed session registration
+
+```text
+track --handoff FILE --provider codex|claude --phase PHASE [--root LOG_DIR]
+      [--from ISO --to ISO --parent KEY --parent-evidence TEXT --configuration ID|--skills-root DIR]
+track --ticket FILE
+```
+
+The first call writes an internal ticket under the bound run's `registrations/` and records a
+pending attempt in the run. It returns a generated marker and `nextCall` as an executable plus
+argument array. The agent executes those arguments in a **separate tool call in the same
+conversation**, quoting for its shell. This lets the first output reach the native transcript.
+It also snapshots the provider's installed skill root (`<project>/.claude/skills` or
+`<project>/.agents/skills`) when present and associates that snapshot with the new session.
+No user-supplied session ID, log path or nonce is necessary. Never reuse a ticket in another
+conversation or put it into a continuation prompt. Tickets contain local metadata, not messages.
+
+The second call uses the marker and exact project to resolve one log and register/import it.
+No/ambiguous matches return `pending` with a reason; retry once later in the same conversation,
+then continue independent work with an explicit gap. Reports include pending attempts. A success
+returns `sessionKey` and an internal ticket handle for checkpoint and close. Repeated calls preserve one session record and its
+original phase; source, bounds, parent or supplied configuration conflicts stay pending. A child
+requires the actual parent and evidence; do not guess it. The flags are internal agent operations.
+
+The helper never confirms coverage or user acceptance. The agent reviews attribution, child logs
+and configuration, records evidence, refreshes usage and generates the report. `collect` refreshes
+registered logs only. An unchanged hash does not prove the conversation ended. After the final
+response the last log may change; refresh at the next entry or from an observer with access to the
+closed log, retaining a pending final-accounting note until then. No model is launched to do this.
+Low-level discover/whoami/session remain available for evidence-based recovery; their IDs are not
+part of the user's normal workflow.
+
+## Bind an existing register
+
+```text
+bind --run <absolute-run.json> --handoff <file> [--task <project-task-id> --plan <file> --state <file>]
+```
+
+Creates the sidecar if absent, with an empty block map and default adjacent PLAN.md/STATE.md.
+When the sidecar exists, preserves its paths, project task ID and planned blocks. Optional path
+arguments resolve from the command working directory, and conflicting arguments are rejected.
+The command writes only the sidecar, never the handoff, plan, state or run. Bind can precede planning;
+checkpoint/next-prompt require the actual documents and complete map.
+
+The generated `measurement` stores `status: enabled`, absolute `run`, its `runId`, benchmark
+`taskId`, and `criteriaHash` (canonical ID/expectation/required contract). The project task ID may
+differ. Handoff must reside within run.project; worktree and main checkout are not interchangeable.
+The agent selects the run from the task's binding or documented location, checking identity and criteria.
+Binding is idempotent. A different run, changed criteria, explicitly disabled measurement or
+conflicting existing paths stop before writes. Do not manually bypass conflicts by deleting the
+sidecar; reconcile moved paths or approved scope changes with the user and preserve the history.
+
+## Open and close a working session
+
+```text
+open --handoff <file> --block B2 [--phase implementation] [--nonce TOKEN]
+close --handoff <file> --block B1 --implementation complete (--next-block B2 | --final)
+      [--ticket TICKET | --session-key provider:id --session-state closed --claim verified]
+```
+
+After setup and registration, `open` inspects an assigned block; `close` saves the continuation,
+checkpoints and refreshes usage. They require existing documents and a complete planned map.
+When the current conversation has a registered ticket, use `close --ticket` so the checkpoint
+automatically reuses its session key. A ticket is valid only in the conversation that created it;
+never transfer it to a later prompt.
+The agent also generates report at closure. Usage is refreshed again at the next entry or by an
+observer after the last response. A new conversation alone does not attest the old one's closure.
+
+`open` retains low-level identity hints for compatibility. Prefer `track` to resolve and register
+together. An unresolved identity stays pending; it is never replaced by the most recent log.
+
+## Check a block without changing anything
+
+```text
+checkpoint --handoff <file> --block B1 --implementation complete
+           [--session-key provider:id --session-state active|closed|unknown --claim verified --next-block B2]
+```
+
+Implementation is an explicit operator/agent declaration: `complete`, `in-progress`, or
+`not-started`. It is not inferred from tests. The computed point status is respectively
+`verified` only with all required passing, intact, fresh evidence; otherwise
+`implemented-unverified`; or `in-progress`/`planned` for the latter two declarations.
+Underlying verification retains failed/blocked/reopened/invalidated distinctions.
+At least one required criterion is needed for automatic verified status; optional-only blocks
+remain unverified. Missing criteria, artifacts, hashes or evidence after reopening never pass.
+
+Optional `--claim` accepts planned, in-progress, implemented-unverified or verified. A conflicting
+claim gives exit code 2 plus the calculated status. Without a claim, code 0 means the inspection
+succeeded, not that the block passed. Invalid binding/map/links produce code 1.
+With `--next-block B2`, it also performs the saved-prompt check below and returns `continuation`
+with `valid` and `status`. A missing, stale or altered prompt gives code 2, even if the current
+block is technically verified; technical `status`, `verification` and `claimMatches` are unchanged.
+Omitting `--next-block` preserves the existing read-only behavior and does not check prompt delivery.
+
+The output separates technical verification from session registration, log freshness and coverage.
+Missing identity remains pending. `--session-state closed` is a declaration, not process detection
+or coverage confirmation. Active/unknown sessions are provisional. A changed log needs collect;
+unavailable logs and parser warnings remain explicit. Registering the session does not prove
+subagent completeness. Checkpoint does not register/import anything automatically.
+
+The command checks the entire map, then only the assigned block's verification. Future unfinished
+blocks do not invalidate an otherwise verified B1. It shows dependency verification but does not
+decide dependency readiness: review which missing checks actually prevent the next work.
+Reconcile STATE.md and the final response with the calculated result. No arbitrary Markdown parser
+claims to detect phrases like "verified except A5"; the agent must use the computed status.
+Evidence hashes establish integrity, not semantic sufficiency. In ordinary projects, reopen and
+reverify after code changes; this version does not fingerprint all business source automatically.
+
+With disabled/unknown measurement, structural checks and prompt generation remain available,
+but acceptance verification reports `not-checked` and cannot yield automatic verified status.
+
+## Generate the next assigned prompt
+
+```text
+next-prompt --handoff <file> --block B2 [--save|--check]
+next-prompt --handoff <file> --clear
+```
+
+Without an option it prints a prompt only. No form chooses a block or launches a session.
+Prepare the first execution prompt during planning, before execution is authorized. When the user
+submits it as the next request, it continues the task from the named block. Generating or reading
+a saved prompt does not authorize anything. Respect newer user restrictions; the helper does not
+infer approval from arbitrary prose or intercept application-writing tools.
+Requires a block from the planned map and existing documents. The prompt is short: absolute handoff,
+state, plan and sidecar paths, the project task ID, the block's points, criteria and dependencies,
+and the measurement status (with run path, both task IDs and accounting instructions only when
+enabled). Task-specific constraints, blockers and Your actions stay in STATE outside the generated
+section; the prompt tells the next session to read STATE first. Worktree ownership, evidence
+reconciliation and authorization rules come from denisco-handoff-implementation itself; an inherited claim
+token is never valid for a newly resumed process.
+Unknown/disabled measurement is explicitly represented. Never use old external PROMPTS.md splits
+to override the current PLAN.md and map.
+
+`--save` writes and rereads the resolved STATE file, returning JSON with `state`, `block`, `changed`,
+`valid`, `status: saved`, and the verified `prompt` (LF-normalized text). `--check` never writes:
+it returns `valid` and `status: saved|missing|stale-or-modified`; a failed check gives exit code 2.
+The prompt is returned only on a successful check. Both compare the actual saved section with
+the current generator and structural context, including the complete block map and measurement
+binding. Updating usage/results alone does not invalidate the prompt. Structural changes or a
+changed generator require another explicit save. After a skill update, regenerate/check saved
+planning prompts and prepared execution prompts with the installed helper; preserve surrounding
+notes and approval evidence. This is not a semantic check of notes or PLAN prose.
+
+The single managed section runs from `<!-- workflow:next-prompt:start -->` to
+`<!-- workflow:next-prompt:end -->`, with a heading, a context fingerprint comment and a fenced
+copyable prompt. Add it on first save, replace it on later saves. All text outside it is preserved,
+including history; separation newlines may be added on first insertion. The writer preserves
+UTF-8 (with/without BOM), BOM-marked UTF-16 LE/BE, and existing outside line endings; generated
+text uses CRLF when present, otherwise LF. Invalid encoded text is rejected rather than repaired.
+Repeated identical saves do not rewrite the file. Duplicate, partial or misordered markers are
+errors (code 1), never a reason to overwrite the whole document. Repair malformed sections first.
+Legacy unmarked prose is preserved; the agent reconciles obsolete manual prompts outside the section.
+
+`--clear` requires no block and rejects `--block`. It removes only the managed section; absent
+sections are an idempotent success. It returns `status: cleared`, `block: null`, `prompt: null`,
+`valid: true` and `changed`. It declares no implementation/acceptance outcome. The three flags are
+mutually exclusive. Saves/clears use a STATE lock, recheck source bytes/context, atomically replace
+through a temporary file and reread the result. A live lock or detected concurrent change stops
+the operation; inspect stale locks manually. Uncooperative writers cannot be prevented from editing
+after the check, so use one writer and keep the closing check last.
+
+At each block's end: finish validation, register evidence, reconcile STATE and run checkpoint for
+that block. When the working session reaches a real stop: save/check the next assignment, then
+checkpoint the last block worked with --next-block. Use the same block for unfinished implementation
+or verification; its pending blockers live in STATE. Do not omit the continuation merely because no
+new block exists or its future launch has not yet been authorized. The working programmer never
+launches the saved continuation itself. An explicitly authorized denisco-implementation-coordinator may dispatch
+the next bounded assignment under the recorded user scope; a worker never launches its successor.
+Clear it only when no task work remains, or the user ends the task or asks for no prompt, retaining
+acceptance and accounting gaps; a user stop with work remaining keeps it. After later code/evidence changes, refresh results and checkpoint again.
+Disabled/unknown measurement supports these structural operations without creating a run.
+In Plan Mode propose artifacts and leave writes pending. Without the helper save/reread manually.
+The helper cannot force its invocation or prove that a user submitted a saved prompt.
+
+## Configuration provenance across upgrades
+
+```text
+configuration --run <file> --skills-root <installed-flat-bundle> --note <provenance>
+              [--loaded denisco-handoff-implementation,denisco-workflow-benchmark]
+session --run <file> ... --configuration <returned-ID>
+session-config --run <file> --session-key provider:id --configuration <ID> --note <attribution>
+```
+
+`configuration` appends a uniquely identified snapshot to configurationHistory: capture/observation
+time, provenance, package file hashes and declared metadata.version. It reads only current files;
+it is not retrospective evidence for B1 after installing B2. It does not import repository tooling
+or a YAML dependency. Simple two-space-indented metadata.version scalars are recognized; unfamiliar
+YAML remains an explicit unknown with a hash, not an invented version. Repository YAML validation
+is a separate stronger check.
+
+Every package is installed-only unless named in `--loaded`, which is an operator attestation
+requiring observed session/tool evidence in the note. Being installed is never proof of loading.
+Neither recording a snapshot nor updating environment automatically attributes it to any session.
+Associate snapshots only with supporting evidence; legacy sessions remain unknown if evidence is
+unavailable. `session-config` requires a note and refuses to replace a different prior attribution.
+Reimport preserves associations. Sessions that genuinely mix skill versions need explicit notes;
+do not describe them as a clean single-version comparison.
+
+`environment` now appends notes without losing the previous legacy environmentReview. Reports keep
+the latest view plus histories and per-session configuration IDs. Skill version/hash changes are
+visible across upgrades, not silently applied to earlier work. Existing schemaVersion 1 registers
+remain readable without rewriting them or guessing missing associations.
+
+## Working-session / operator boundary
+
+The working session records real evidence and identified session IDs. If its own identity is not
+available after the bounded retry, record the pending action for later evidence-based recovery;
+do not ask the user to find IDs or choose the latest log blindly. One native session mixing planning
+and implementation counts once under its registered phase.
+After closure, collect and report finalize observed logs, while coverage still requires review.
+Keep exploration separately visible. Measurement-only agent overhead is distinct from implementation.
+Capture changes to the workflow configuration between blocks; different business blocks are not a
+matched token-efficiency experiment. No helper authorizes paid runs, production writes or new tests.
+
+## Visual checks and optional delegation
+
+An optional sidecar visualChecks array identifies checks by unique id, block, nonempty criteria,
+executor "principal" or "subagent", and optional required: false. New ordinary checks use principal.
+Only an explicit user request delegates the whole check; a perceptual blind judge remains a separate
+child used when applicable and permitted. Its result and native usage do not replace the executor.
+
+Use visual-start --executor principal|subagent before capture, with --principal-session when known,
+and visual-finish with --session-key of the executor, --loaded true|false, --results JSON and
+--evidence files afterwards. Explicitly load denisco-visual-check and refresh the registered executor log
+before finish. Principal checks require a top-level session matching the recorded principal;
+delegated checks require a registered child whose parent matches that principal. Skill loading
+must appear in the executor's native log (Skill tool or slash command). Missing proof remains
+unverified; installation or an agent's assertion alone is insufficient.
+
+For compatibility, omitting --executor retains the legacy subagent behavior; new workflow calls
+always name principal or the user's requested subagent. Existing run records without executor are
+read as legacy delegated attempts. Existing sidecars already name subagent and stay readable.
+Do not relabel historical attempts to satisfy a new policy. For future checks reconcile an old
+delegated assignment against the current user request, preserve history and choose a new attempt ID.
+
+Checkpoint validates the executor, session attribution, block and passing results for all assigned
+criteria. It never accepts principal evidence for an explicitly delegated assignment or vice versa.
+Evidence relevance remains an agent responsibility. Finish also stores artifact hashes and duration.
+Record criterion evidence through result as usual. With disabled measurement use STATE as the record.
+
+Only the implementation owner updates shared state and the register. Delegated visual-only checkers write their exclusive
+attempt directory; the principal merges index rows. Keep measured code/tooling stable during capture.
+Close resources created solely for the check on success, failure or cancellation, preserving existing
+services and explicitly needed follow-up resources. Close/release returned children where supported;
+report cleanup limitations rather than claiming process exit.
+
+Inspect existing evidence and native logs before scheduling a replacement. For Claude children,
+the native JSONL is normally in the conversation's subagents directory: verify root sessionId and
+agentId in its records, register with --id ROOT_ID --agent AGENT_ID and the evidenced parent.
+A temporary task .output file is not the native transcript. Other providers require their actual
+native identity and relationship. Include the blind judge separately; missing attribution leaves
+coverage pending and never warrants inventing usage or launching a model just to count it.
+
+## Coordinated execution
+
+With denisco-implementation-coordinator explicitly authorized, follow denisco-handoff-implementation's bounded
+assignment and ownership contract. Its preparation writes COORDINATOR, COORDINATOR-HISTORY and
+packet files, then reaches a separate execution boundary. When planning selects the coordinated path,
+planning and preparation share the planning registration. Register the coordinator before its actual native
+children when measurement is enabled and bound: use planning for preparation or implementation for
+an execution-only entry, with a coordination note. One native conversation spanning both phases
+retains one registration with its actual history explained. Record overhead rather than hiding it.
+Register a programming worker with its actual parent evidence. Each worker keeps its own ticket.
+The worker owns the worktree and may update the run and sidecar; the coordinator only reads until
+the worker finishes and releases. Parent registration failures leave child accounting pending and
+never justify registering a native child as a top-level session. Independent implementation continues.
+The coordinator may register/refresh/report measurement under its own claim between workers, but
+never writes HANDOFF, PLAN, STATE, STATE-HISTORY or the sidecar, including through `close`, `bind`,
+planning-prompt or next-prompt save/clear. Missing measurement setup or technical prompt repairs
+belong to the standard worker workflow. Preserve pending attribution if setup cannot yet complete.
+
+A programming worker performs its own visual checks. For a native child use executor `subagent`,
+the worker's session key and its actual parent as principal session. The initial explicit request
+to coordinate implementation includes its required checks. Reconcile future sidecar visualChecks
+entries accordingly; preserve historical attempts. This changes no executor validation rules:
+operational ownership is distinct from native parentage. Register a blind judge under its actual
+caller, including when the coordinator relays a blind packet for a worker unable to spawn children.
+Visual-only checkers retain their exclusive artifact scope and never write shared registers.
+
+Keep the bounded assignment and coordinator launch/resume prompt in COORDINATOR, with coordination
+events in COORDINATOR-HISTORY. The programmer reads those files and updates only technical documents
+through denisco-handoff-implementation; the coordinator never appends technical history on its behalf.
+STATE contains the short coordination reference and its ordinary generated next-prompt section.
+The helper still generates a generic starting-block prompt; the coordinator supplies the exact
+allowed block list and return boundary separately. After the final implementation block, retain
+that block as the continuation anchor while STATE names pending integration; clear only when no
+task work remains or the user explicitly cancels. Existing helpers do not launch workers or prove
+that they respected their range. Cumulative usage is not live context occupancy; coordination does
+not activate measurement when the sidecar is disabled.

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

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { requireValue, readJSON, writeJSON, loadRun, mutateRun, now } from './io.mjs';
+import { createRun, registerSession, collect, recordEvidence, evaluate, report, compare, startVisualCheck, finishVisualCheck } from './runs.mjs';
+import { prepare, checkProtected } from './prepare.mjs';
+import { discover, whoami } from './discover.mjs';
+import { bind, checkpoint, close, nextPrompt, open, planningPrompt } from './workflow.mjs';
+import { track } from './tracking.mjs';
+import { captureConfiguration, attachConfiguration, recordEnvironment } from './configuration.mjs';
+
+const HELP = `Workflow benchmark (Node 20+, no model launches)
+  track --handoff FILE --provider codex|claude --phase PHASE [--root LOG_DIR]
+        [--from ISO --to ISO --parent KEY --parent-evidence TEXT --configuration ID|--skills-root DIR]
+  track --ticket FILE
+  planning-prompt --handoff FILE [--save|--check]
+  open --handoff FILE --block ID [--phase PHASE] [--provider codex|claude] [--nonce TOKEN]
+  close --handoff FILE --block ID --implementation complete|in-progress|not-started
+          (--next-block ID | --final) [--ticket FILE|--session-key provider:id] [--session-state STATE --claim STATUS]
+  whoami --provider codex|claude --nonce TOKEN [--project DIR --root LOG_DIR]
+  discover --provider codex|claude --project DIR [--root LOG_DIR --limit 20]
+  init --out DIR --task ID --project DIR --variant NAME --criteria JSON
+  bind --run FILE --handoff FILE [--task PROJECT_TASK --plan FILE --state FILE]
+  checkpoint --handoff FILE --block ID --implementation complete|in-progress|not-started
+          [--session-key provider:id --session-state active|closed|unknown --claim STATUS --next-block ID]
+  next-prompt --handoff FILE --block ID [--save|--check]
+  next-prompt --handoff FILE --clear
+  configuration --run FILE --skills-root DIR --note TEXT [--loaded name,name]
+  session-config --run FILE --session-key provider:id --configuration ID --note TEXT
+  prepare --out DIR --case order-filter|order-summary --variant baseline|candidate
+          --provider codex|claude [--baseline MANIFEST]
+  session --run FILE --provider codex|claude --id NATIVE_ID --log JSONL --phase PHASE
+          [--from ISO --to ISO] [--agent ID --parent provider:id --parent-evidence TEXT] [--coverage-confirmed] [--configuration ID]
+  visual-start --run FILE --id ATTEMPT --block ID --criteria ID[,ID] [--executor principal|subagent] [--principal-session KEY] [--at ISO]
+  visual-finish --run FILE --id ATTEMPT --session-key EXECUTOR_KEY --loaded true|false [--results JSON] [--evidence FILE[,FILE]] [--at ISO]
+  collect --run FILE [--coverage-confirmed]
+  result --run FILE --criterion ID --status pass|fail|not-run --observation TEXT [--evidence FILE]
+  review --run FILE --status accepted|reopened|pending --note TEXT
+  environment --run FILE --note TEXT
+  intervention --run FILE --kind clarification|correction|approval|environment --note TEXT
+  evaluate --run FILE
+  report --run FILE
+  compare --runs FILE,FILE [--out JSON]
+Phases: exploration, specification, planning, implementation, verification, correction.
+Options use separate values; quote paths with spaces. Log paths and native IDs are explicit.
+`;
+const allowed = {
+  track: ['handoff', 'provider', 'phase', 'root', 'ticket', 'from', 'to', 'parent', 'parent-evidence', 'configuration', 'skills-root'],
+  'planning-prompt': ['handoff', 'save', 'check'],
+  bind: ['run', 'handoff', 'task', 'plan', 'state'],
+  open: ['handoff', 'block', 'phase', 'nonce', 'provider'],
+  close: ['handoff', 'block', 'implementation', 'next-block', 'final', 'session-key', 'session-state', 'claim', 'ticket'],
+  whoami: ['provider', 'project', 'nonce', 'root'],
+  checkpoint: ['handoff', 'block', 'implementation', 'session-key', 'session-state', 'claim', 'next-block'],
+  'next-prompt': ['handoff', 'block', 'save', 'check', 'clear'],
+  configuration: ['run', 'skills-root', 'note', 'loaded'],
+  'session-config': ['run', 'session-key', 'configuration', 'note'],
+  discover: ['provider', 'project', 'root', 'limit'],
+  init: ['out', 'task', 'project', 'variant', 'criteria'],
+  prepare: ['out', 'case', 'variant', 'provider', 'baseline'],
+  session: ['run', 'provider', 'id', 'agent', 'log', 'phase', 'from', 'to', 'parent', 'parent-evidence', 'coverage-confirmed', 'configuration'],
+  'visual-start': ['run', 'id', 'block', 'criteria', 'executor', 'principal-session', 'at'],
+  'visual-finish': ['run', 'id', 'session-key', 'loaded', 'results', 'evidence', 'at'],
+  collect: ['run', 'coverage-confirmed'], result: ['run', 'criterion', 'status', 'observation', 'evidence'],
+  review: ['run', 'status', 'note'], environment: ['run', 'note'], intervention: ['run', 'kind', 'note'],
+  evaluate: ['run'], report: ['run'], compare: ['runs', 'out']
+};
+export function main(args) {
+  const [command, ...rest] = args;
+  if (!command || ['help', '--help'].includes(command)) return HELP;
+  if (!allowed[command]) throw new Error(`Unknown command: ${command}`);
+  const opts = {};
+  for (let i = 0; i < rest.length; i++) {
+    const key = rest[i].slice(2);
+    if (!rest[i].startsWith('--') || !allowed[command].includes(key) || key in opts) throw new Error(`Invalid/duplicate option ${rest[i]}`);
+    opts[key] = ['coverage-confirmed', 'save', 'check', 'clear', 'final'].includes(key) ? true : requireValue(rest[++i], key);
+  }
+  const need = name => requireValue(opts[name], `--${name}`);
+  if (command === 'track') return track({ handoff: opts.handoff, provider: opts.provider, phase: opts.phase,
+    root: opts.root, ticket: opts.ticket, from: opts.from, to: opts.to, parent: opts.parent,
+    parentEvidence: opts['parent-evidence'], configurationId: opts.configuration, skillsRoot: opts['skills-root'] });
+  if (command === 'planning-prompt') {
+    const result = planningPrompt({ handoff: need('handoff'), save: opts.save, check: opts.check });
+    if (result.valid === false) process.exitCode = 2;
+    return result;
+  }
+  if (command === 'open') {
+    const result = open({ handoff: need('handoff'), block: need('block'), phase: opts.phase, nonce: opts.nonce, provider: opts.provider });
+    if (result.continuation.valid === false) process.exitCode = 2;
+    return result;
+  }
+  if (command === 'close') {
+    const result = close({ handoff: need('handoff'), block: need('block'), implementation: need('implementation'),
+      nextBlock: opts['next-block'], final: opts.final ?? false, sessionKey: opts['session-key'],
+      sessionState: opts['session-state'], claim: opts.claim, ticket: opts.ticket });
+    if (!result.claimMatches || result.continuation?.valid === false) process.exitCode = 2;
+    return result;
+  }
+  if (command === 'whoami') return whoami({ provider: need('provider'), project: opts.project, nonce: need('nonce'), root: opts.root });
+  if (command === 'bind') return bind({ handoff: need('handoff'), run: need('run'), task: opts.task, plan: opts.plan, state: opts.state });
+  if (command === 'checkpoint') {
+    const result = checkpoint({ handoff: need('handoff'), block: need('block'), implementation: need('implementation'), sessionKey: opts['session-key'], sessionState: opts['session-state'], claim: opts.claim, nextBlock: opts['next-block'] });
+    if (!result.claimMatches || result.continuation?.valid === false) process.exitCode = 2;
+    return result;
+  }
+  if (command === 'next-prompt') {
+    const result = nextPrompt({ handoff: need('handoff'), block: opts.clear ? opts.block : need('block'), save: opts.save, check: opts.check, clear: opts.clear });
+    if (result.valid === false) process.exitCode = 2;
+    return result;
+  }
+  if (command === 'configuration') return captureConfiguration(need('run'), { skillsRoot: need('skills-root'), note: need('note'), loaded: opts.loaded?.split(',') ?? [] });
+  if (command === 'session-config') return attachConfiguration(need('run'), { sessionKey: need('session-key'), configurationId: need('configuration'), note: need('note') });
+  if (command === 'discover') return discover({ provider: need('provider'), project: need('project'), root: opts.root, limit: opts.limit === undefined ? 20 : Number(opts.limit) });
+  if (command === 'init') return createRun({ out: need('out'), task: need('task'), project: need('project'), variant: need('variant'), criteria: readJSON(need('criteria')) });
+  if (command === 'prepare') return prepare({ out: need('out'), caseId: need('case'), variant: need('variant'), provider: need('provider'), baseline: opts.baseline });
+  if (command === 'session') return registerSession(need('run'), { provider: need('provider'), sessionId: need('id'), agentId: opts.agent, log: need('log'), phase: need('phase'), from: opts.from, to: opts.to, parent: opts.parent, parentEvidence: opts['parent-evidence'], coverageConfirmed: opts['coverage-confirmed'] ?? false, configurationId: opts.configuration });
+  if (command === 'visual-start') return startVisualCheck(need('run'), { id: need('id'), block: need('block'), criteria: need('criteria').split(','), executor: opts.executor, principalSession: opts['principal-session'], at: opts.at });
+  if (command === 'visual-finish') {
+    if (!['true', 'false'].includes(need('loaded'))) throw new Error('--loaded must be true or false');
+    return finishVisualCheck(need('run'), { id: need('id'), sessionKey: need('session-key'), skillLoaded: opts.loaded === 'true', results: opts.results ? readJSON(opts.results) : [], evidence: opts.evidence ? opts.evidence.split(',') : [], at: opts.at });
+  }
+  if (command === 'collect') return collect(need('run'), { coverageConfirmed: opts['coverage-confirmed'] ?? false });
+  if (command === 'result') return recordEvidence(need('run'), { criterion: need('criterion'), status: need('status'), observation: need('observation'), evidence: opts.evidence });
+  if (command === 'review') {
+    if (!['accepted', 'reopened', 'pending'].includes(need('status'))) throw new Error('Invalid review status');
+    return mutateRun(need('run'), run => {
+      const event = { type: opts.status, note: need('note'), at: now(), evidenceCount: run.evidence.length };
+      run.history.push(event); run.review = { status: opts.status, note: opts.note, at: event.at };
+    });
+  }
+  if (command === 'environment') return recordEnvironment(need('run'), need('note'));
+  if (command === 'intervention') {
+    if (!['clarification', 'correction', 'approval', 'environment'].includes(need('kind'))) throw new Error('Invalid intervention kind');
+    return mutateRun(need('run'), run => { run.interventions.push({ kind: opts.kind, note: need('note'), at: now() }); });
+  }
+  if (command === 'evaluate') {
+    const run = loadRun(need('run')), changed = checkProtected(run);
+    if (changed.length) throw new Error(`Benchmark contaminated: protected files changed: ${changed.join(', ')}`);
+    const result = evaluate(opts.run);
+    if (!result.passed) process.exitCode = 2;
+    return result;
+  }
+  if (command === 'report') return report(need('run'));
+  if (command === 'compare') {
+    const files = need('runs').split(',');
+    if (files.length < 2) throw new Error('At least two runs are required');
+    const result = compare(files);
+    if (opts.out) writeJSON(opts.out, result);
+    return result;
+  }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { const result = main(process.argv.slice(2)); console.log(typeof result === 'string' ? result : JSON.stringify(result, null, 2)); }
+  catch (e) { console.error(e.message); process.exitCode = 1; }
+}

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

@@ -0,0 +1,46 @@
+export const CASES = {
+  'order-filter': {
+    title: 'Bug: filtro ordini coerente tra dashboard ed esportazione',
+    criteria: [
+      { id: 'filter', expectation: 'Il filtro restituisce soltanto gli ordini dello stato richiesto.' },
+      { id: 'consumers', expectation: 'Dashboard ed esportazione usano la stessa regola corretta.' },
+      { id: 'regression', expectation: 'All, input vuoto, ordine originale e dati non mutati restano corretti.' }
+    ],
+    files: {
+      'src/orders.mjs': `export function filterOrders(orders, status = 'all') {\n  return status === 'all' ? [...orders] : orders.filter(order => order.status !== status);\n}\n`,
+      'src/dashboard.mjs': `import { filterOrders } from './orders.mjs';\nexport const dashboardOrders = (orders, status) => filterOrders(orders, status);\n`,
+      'src/export.mjs': `import { filterOrders } from './orders.mjs';\nexport const exportOrders = (orders, status) => filterOrders(orders, status);\n`
+    },
+    reference: {
+      'src/orders.mjs': `export function filterOrders(orders, status = 'all') {\n  return status === 'all' ? [...orders] : orders.filter(order => order.status === status);\n}\n`
+    },
+    points: `## P1 — Correggere il filtro condiviso\n\nReady. Il comportamento atteso è uguaglianza dello stato, non esclusione. Riproduzione: tre ordini pending/completed/cancelled, filtro completed: deve restare solo completed. La causa è l'operatore in src/orders.mjs, filterOrders.\n\nRiutilizzare filterOrders per entrambi i consumatori src/dashboard.mjs e src/export.mjs. Non mutare input o ordine degli elementi. All restituisce tutti gli ordini; uno stato assente restituisce un array vuoto. Nessuna modifica backend esterna, UI o nuovo requisito visuale. Difficoltà verde, dipendenze nessuna.\n`
+  },
+  'order-summary': {
+    title: 'Feature: riepilogo ordini condiviso',
+    criteria: [
+      { id: 'summary', expectation: 'summarizeOrders restituisce total e byStatus per pending/completed/cancelled.' },
+      { id: 'consumers', expectation: 'dashboardSummary ed exportSummary restituiscono il riepilogo condiviso.' },
+      { id: 'regression', expectation: 'Zero per categorie vuote; filtri precedenti e input restano invariati.' }
+    ],
+    files: {
+      'src/orders.mjs': `export function filterOrders(orders, status = 'all') {\n  return status === 'all' ? [...orders] : orders.filter(order => order.status === status);\n}\n`,
+      'src/dashboard.mjs': `import { filterOrders } from './orders.mjs';\nexport const dashboardOrders = (orders, status) => filterOrders(orders, status);\n`,
+      'src/export.mjs': `import { filterOrders } from './orders.mjs';\nexport const exportOrders = (orders, status) => filterOrders(orders, status);\n`
+    },
+    reference: {
+      'src/orders.mjs': `export function filterOrders(orders, status = 'all') {\n  return status === 'all' ? [...orders] : orders.filter(order => order.status === status);\n}\nexport function summarizeOrders(orders) {\n  const byStatus = { pending: 0, completed: 0, cancelled: 0 };\n  for (const order of orders) byStatus[order.status]++;\n  return { total: orders.length, byStatus };\n}\n`,
+      'src/dashboard.mjs': `import { filterOrders, summarizeOrders } from './orders.mjs';\nexport const dashboardOrders = (orders, status) => filterOrders(orders, status);\nexport const dashboardSummary = orders => summarizeOrders(orders);\n`,
+      'src/export.mjs': `import { filterOrders, summarizeOrders } from './orders.mjs';\nexport const exportOrders = (orders, status) => filterOrders(orders, status);\nexport const exportSummary = orders => summarizeOrders(orders);\n`
+    },
+    points: `## P1 — Aggiungere la regola pura\n\nReady. Esportare summarizeOrders(orders) da src/orders.mjs. Input: array di ordini con status tra pending, completed e cancelled; valori fuori contratto esclusi. Output esatto: { total: numero, byStatus: { pending: numero, completed: numero, cancelled: numero } }. Categorie assenti e input vuoto hanno zero; non mutare gli ordini. Il riepilogo riguarda tutti gli ordini passati, non un filtro implicito. Difficoltà gialla, nessuna dipendenza.\n\n## P2 — Collegare i consumatori\n\nReady. Esportare dashboardSummary da src/dashboard.mjs ed exportSummary da src/export.mjs; entrambe accettano orders e restituiscono il contratto di P1. Riutilizzare la regola condivisa. Conservare le funzioni filtro precedenti. Difficoltà verde, dipende da P1. Nessuna nuova UI, persistenza o servizio esterno.\n`
+  }
+};
+
+export function handoff(caseId) {
+  const c = CASES[caseId];
+  if (!c) throw new Error('Unknown case');
+  return `Execute this document with the installed handoff implementation skill. Visual checks are not applicable to this headless task.\n\n# ${c.title}\n\nTask: ${caseId}. This is decided target behavior; no product decisions remain.\n\nBaseline: src/orders.mjs contains a shared filter consumed by dashboard and export. Follow AGENTS.md.\n\n${c.points}\n## Acceptance\n\n${c.criteria.map(x => `- ${x.id}: ${x.expectation}`).join('\n')}\n\nVerification: run node smoke.mjs, plus focused tests you add for these acceptance rules. The operator runs the external fixed evaluator after implementation; do not inspect it or reference solutions. No browser or login is needed.\n`;
+}
+
+export const smoke = `import assert from 'node:assert/strict';\nimport { filterOrders } from './src/orders.mjs';\nassert.deepEqual(filterOrders([]), []);\nconsole.log('Existing smoke check passed; acceptance checks are additional.');\n`;