@deniscodp/skills 0.0.0-stage → 1.0.0

package/skills/denisco-visual-check/references/project-config.md

@@ -0,0 +1,118 @@
+# Visual configuration contract
+
+Execution/authentication instructions belong to the project operating guide. This file defines
+capture coordinates only. Reuse existing project configuration before creating another file.
+
+## Location and compatibility
+
+Use the path named by project instructions. Otherwise look for an existing
+`.agent/visual-check.json`. If needed, use the established agent-local directory.
+Legacy `$schema: "visual-check/1"` configurations remain readable; the value is a format marker,
+not a URL to fetch. Preserve unknown fields. Do not automatically migrate or overwrite them.
+
+Configuration is optional for user-supplied screenshots and standalone mockups. For real app
+capture require a known URL and executable access procedure, not a mandatory new JSON file.
+If startup is needed, resolve a command from the operating guide or legacy app section.
+
+## Fields and defaults
+
+| Field | Meaning/default |
+|---|---|
+| app | Optional URL and serveCommand; omit when there is no runnable app |
+| app.reuseIfListening | true; verify it is the intended app before reusing |
+| app.readyWhen | Optional path and selector indicating readiness |
+| operatingGuide | Optional path to shared start/auth/test instructions |
+| auth | Legacy none or interactive-once; absence means unspecified, not proof of no auth |
+| auth.signedInWhen | Selector proving authenticated state |
+| auth.sessionFile | Local ignored session state; treat as sensitive |
+| environment | Explicit shared/readOnly flags; unspecified write policy means no write tests |
+| artifactsDir | Default .agent/visual-check; local ignored capture outputs, grouped per task |
+| toolingDir | Optional path outside the worktree holding tooling reused across worktrees |
+| viewport | Default width 1440, height 900, deviceScaleFactor 1 |
+| theme | Default system; record actual rendered theme for each capture |
+| routes | Symbolic names to paths |
+| fixtures | Symbolic case names to reproducible, non-sensitive data coordinates |
+
+For interactive-once auth, use a headed human login, save state in an ignored location and verify
+signedInWhen when reusing. An expired session needs renewed login or the project's authorized
+authentication procedure, not password guessing.
+
+The saved session, the login helper and helpers reused across worktrees belong in toolingDir:
+machine-local, never credentials, and named in the operating guide so a new worktree finds them.
+artifactsDir stays per worktree and holds outputs. Without toolingDir the tooling is per worktree
+and does not survive a new checkout; say so rather than leaving it to be discovered.
+
+Navigation, menus, flags, login and environment behavior belong to the operating guide, not to this
+file. Keep coordinates here: routes, viewport, symbolic fixture names pointing at the guide.
+Duplicated prose goes stale and then contradicts the guide. Migrate an existing note bag as you
+touch it, not in one pass.
+
+Use the same operating-guide reference for business behavior and visual checks. Do not duplicate
+service/login facts in every handoff. Record discovered versus actually executed procedures.
+Creating local artifact/config directories must respect project instructions and active write
+permissions. Never automatically broaden shared-environment write permissions.
+
+## Artifact layout and index
+
+Artifacts live under `artifactsDir`, one folder per task named with the handoff task ID, and the
+outputs of a single run in a subfolder of it. Only the index and helpers shared across tasks stay
+at its root; what is reused across worktrees, the browser profile included, belongs to toolingDir.
+A task's probes, captures and logs are then retrievable from its name alone, without grepping
+unrelated files.
+
+```
+<toolingDir>/                          shared across worktrees, outside the repository
+  profile/                             saved session state
+  login.mjs                            headed login helper
+  lib/                                 helpers reused across worktrees
+
+.agent/
+  visual-check.json                    configuration
+  visual-check/                        artifactsDir, per worktree
+    INDEX.md                           index of every probe and diagnostic
+    dss-fase3-special-fields/          one folder per task
+      probe-v1-v3.mjs
+      probe-v1-v3/                     outputs of one run
+        stato.png
+        diag.json
+      diag-tabella-vuota.mjs
+```
+
+`INDEX.md` carries one row per probe or diagnostic:
+
+```
+| Task | Artifact | Covers | Needs | Status | Updated |
+|---|---|---|---|---|---|
+| dss-fase3-special-fields | dss-fase3-special-fields/probe-v1-v3.mjs | V1, V2, V3 | selected group, saved filter cleared | current | 2026-09-14 |
+| dss-fase3-appuntamento | dss-fase3-appuntamento/probe-punto2.mjs | P2-A1 | selected group | superseded by dss-fase3-special-fields/probe-v1-v3.mjs | 2026-09-11 |
+```
+
+Read it before creating a probe. A principal (the implementation owner, including a bounded
+programming worker with its own claim) adds or updates the row when finishing one; a delegated visual-only
+child returns proposed rows for the principal to merge, without writing the shared index. Give each
+child an exclusive `<taskId>/<attemptId>/` directory for both probe copies and outputs. Children
+read shared helpers but report needed repairs to the principal rather than changing them concurrently.
+An artifact missing from the index is harder for the next session to find; absence from the index
+alone does not prove missing evidence. Keep superseded rows and name the successor: deleting
+them loses why a probe was replaced. Name in Needs the environment preconditions a probe depends
+on, such as a selected group or a saved filter; their values live in the operating guide, where
+they serve everyone. A rediscovered prerequisite costs a full diagnostic run. Criterion outcomes
+do not belong here.
+
+Legacy flat layouts stay valid. Index them where they are and adopt the per-task layout for new
+artifacts instead of rewriting an accumulated directory in one pass.
+
+## Example
+
+```json
+{
+  "$schema": "visual-check/1",
+  "operatingGuide": "docs/agent-workflow/OPERATIONS.md",
+  "app": { "url": "http://localhost:5173", "serveCommand": "npm run dev" },
+  "environment": { "shared": false, "readOnly": true },
+  "viewport": { "width": 1440, "height": 900, "deviceScaleFactor": 1 },
+  "routes": { "orders": "/orders" }
+}
+```
+
+Missing fixtures remain unresolved prerequisites for those cases; do not invent values.

package/skills/denisco-workflow-benchmark/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: denisco-workflow-benchmark
+description: "Prepare reproducible workflow comparisons, register task sessions, import local Codex/Claude usage and report evidence-backed outcomes. Use only when workflow measurement or benchmarking is explicitly requested; not for ordinary task execution, implicit measurement, prose-only completion judgments or launching paid runs."
+metadata:
+  version: "5.1.0"
+---
+
+# Workflow benchmark
+
+Use [the CLI and data contract](references/measurement.md) before collecting or preparing a run.
+The executable is [scripts/bench.mjs](scripts/bench.mjs); it works with Node 20+ and never launches
+a model. Locate it relative to this installed skill, not a remembered developer workstation path.
+For real tasks read [persistent handoff and closure](references/workflow-contract.md).
+Use `bind` to persist the explicit run in `<handoff-path>.workflow.json`; a later session must
+discover it from the handoff alone, not rely on external PROMPTS.md as the only connection.
+
+Task workflow measurement is opt-in. Use this skill only after the current user request or applicable
+project instructions explicitly activate measurement for this task. Installation, skill discovery,
+acceptance criteria, an old register and `measurement.status: unknown` are not activation. Disabled
+is authoritative: do not bind, register, collect or rewrite prompts for that task. When explicitly
+enabled, the agent owns setup, retries, collection and reporting; users receive outcomes rather than
+session IDs, nonces or commands. Follow the operational contract and preserve existing bindings.
+After specification save/check `planning-prompt` in HANDOFF; it requires no plan or block.
+Planning prompts assign PLAN/STATE, the block map and a saved/checked first execution prompt, then
+the start question; only the user's yes to it, or a later submitted execution prompt, starts
+implementation. Native Plan Mode approval never does. Submitting a saved execution prompt as the
+user's request continues the task from the named block; reading or generating it does not.
+A working session then continues block by block until a real stop defined by denisco-handoff-implementation.
+Keep phase boundaries independent of tool mode.
+For handoff planning/implementation, acquire the denisco-handoff-implementation worktree claim before
+registration or any other write. Conversation registration deduplicates usage; it does not claim
+execution ownership. A second process with the same conversation ID remains a separate writer.
+An observer blocked by ownership may read records or run `checkpoint`, but not `open`, `track`,
+`collect`, `report` or `close`, which write. Delegated visual-only children return evidence for the
+implementation owner to register; they do not mutate the shared run themselves. A bounded programming
+worker with its own claim records its own evidence while the coordinator stays read-only. Follow
+the coordinated execution section of the persistent workflow contract.
+Between workers, a coordinator may register/refresh permitted measurement records under its own
+claim, but leaves technical documents unchanged: its prompts and history belong in COORDINATOR
+and COORDINATOR-HISTORY. `close`, `bind` and technical prompt save/clear stay with the standard
+specification/implementation workflow; they are not coordinator bookkeeping commands.
+
+Keep the task and acceptance fixed before measurement. Separate exploration investment, task work
+and correction. Register native session IDs explicitly; do not attribute the latest unrelated log.
+Use one task per session in v1, or explicit time bounds for mixed/resumed histories.
+
+After registration, use `open` when the planned block map exists: it refreshes registered logs
+and prints the register and assignment. An unchanged log does not prove its conversation ended.
+The agent runs collect/report at closure and refreshes them on the next entry; the final response's
+trailing usage remains pending until an observer can refresh it. Close with `close`, which saves the prepared
+continuation, checkpoints the block and refreshes usage. Both compose existing commands and attest
+nothing: coverage, acceptance and the claimed status stay explicit decisions.
+
+Register the current conversation with `track --handoff <file> --provider <actual-provider>
+--phase <actual-phase>`, then execute the returned nextCall yourself in a separate tool call.
+The helper generates the marker, resolves the unique log and registers it; existing registration
+is reused without double counting. The helper snapshots the provider's installed skill bundle
+when available and associates it with the new session. If pending, retry once later in the same
+conversation, then report the gap. Keep the returned ticket internal; use it with
+`close --ticket <ticket>` in this same conversation so close reuses the registered identity.
+Never copy the ticket into the next-session prompt. Low-level whoami/session remain available for
+diagnostics and historical recovery with positive attribution evidence.
+
+Collect usage from local logs through the CLI. Never estimate tokens or copy conversations into
+reports. Inspect coverage warnings, duplicates, parent/child attribution and version information.
+Missing metrics remain null, not zero. Reimport after the session has finished for final accounting.
+The working session records evidence and its identity when known; an operator/observer finalizes
+usage after closure. If identity is ambiguous, leave an explicit pending action. Do not launch a
+model solely to measure known IDs. Keep measurement-only agent overhead separately visible.
+
+Evaluate acceptance using recorded evidence or the prepared external verifier. An agent's summary
+does not mark a task verified. Record user acceptance/reopening separately and preserve history.
+
+Compare matched cases within the same provider/model/settings first. Include failures and blocked
+runs, not just successful ones. Report quality before resource use; do not turn different tokenizers
+into a claim that one provider is universally more efficient. Small pilots are descriptive only.
+
+Preparing a benchmark does not authorize a model run. Return ready-to-paste prompts and commands.
+For controlled cases, keep evaluator and reference solutions outside the working copy. This is a
+procedural boundary, not an OS sandbox: record evidence of inspection or instruction contamination.
+
+After each block's validation and evidence registration, update STATE and run `checkpoint` for that
+block. When the working session stops, use `next-prompt --save` for the proposed next assignment or
+same-block resume, then `checkpoint --next-block` to check both the last block worked and the
+persisted prompt. A same-block resume is allowed; no command chooses the assignment.
+`next-prompt --check` is read-only; plain `next-prompt` only prints and does not satisfy delivery.
+The scripts check integrity/completeness and their generated section, not artifact relevance or
+arbitrary Markdown claims. Keep custom notes outside that section. Link the saved STATE in the
+response; any prompt copied into chat must match the saved text. When no task work remains, or the user ends the task or asks for no prompt, use `--clear`
+and checkpoint without `--next-block`, retaining unresolved acceptance/accounting in STATE.
+These structural operations work with measurement disabled/unknown. In Plan Mode leave writes
+pending. Later changes to code or evidence require refreshed results and another checkpoint.
+
+A skill can be loaded by the Skill tool or by typing its slash command; the register records both
+and being installed still proves neither. A report marks each session's usage final, stale or
+unavailable by rehashing its log, so a skipped collect is visible instead of silent.
+
+Capture skill configuration with `configuration` and associate it explicitly with sessions.
+Read `metadata.version`, not a top-level version; retain hashes if the version is unknown.
+
+For visual checks the principal is the default executor. Delegate the whole check only on explicit
+user request; a blind perceptual judge remains independently delegated when available and permitted.
+Use visual-start --executor principal|subagent before the check and visual-finish after it, with the
+registered executor session, explicit skill loading, criterion results and artifacts. Refresh the
+executor's log before finish so loading is observed. A principal check requires a top-level session;
+a delegated check requires a child attributed to the named principal. Register judge usage separately.
+Legacy records keep their executor; never reinterpret a historical delegated attempt as a principal
+one. Inspect artifacts and native logs to repair registration gaps before scheduling a replacement.
+For Claude children, use the native JSONL under the conversation's subagents directory with its
+recorded root sessionId plus agentId, not a temporary task .output file or agentId as sessionId.
+Use actual native metadata and invocation evidence on every provider; ambiguity stays pending.
+Installed files are not proof of loading. Preserve configuration/environment history across
+upgrades; never attribute today's installed versions to earlier sessions without evidence.

package/skills/denisco-workflow-benchmark/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,166 @@
+# Measurement contract and CLI
+
+Run `node <installed-skill>/scripts/bench.mjs help`. Node 20+ is the only runtime dependency.
+The CLI never launches a model. Its `evaluate` command runs local case code in a child Node process.
+
+## Run identity and commands
+
+For ordinary task work the agent uses `track` and `planning-prompt` following
+[setup and registration](workflow-contract.md#agent-managed-setup-and-first-handoff).
+`track --handoff FILE --provider codex|claude --phase PHASE` emits an internal ticket and nextCall;
+execute that nextCall in a separate tool call to identify and register this conversation together.
+When the provider skill root is present in the project, the helper snapshots and associates it
+with the new session. Keep the ticket for the same conversation's `close --ticket` call; never
+put it in the next-session prompt.
+It works before planning and reports delayed/ambiguous identification as pending, also in reports.
+Optional scope/parent/configuration flags and retry limits are in that contract. The low-level
+commands below remain available; the user does not fill their IDs or nonces in the normal flow.
+
+A task is the feature/bug, a block is a plan unit, and a session is a native conversation/log.
+Planning and implementation in the same conversation are counted once, preserving the registered
+phase. A resumed conversation is not automatically a new session. A nonce is only the helper's
+temporary marker for locating a log; it is not a task or block identifier.
+
+`init --out DIR --task ID --project DIR --variant NAME --criteria FILE` creates a new run manifest.
+Criteria input is a JSON array of `{ "id": "A1", "expectation": "observable result" }`; required
+defaults to true, and at least one required criterion is necessary. Existing directories are refused.
+
+`open --handoff FILE --block ID [--phase PHASE] [--nonce TOKEN]` inspects an assigned block: it
+validates the sidecar, runs `collect` on the bound run, reports each session's usage delta and
+freshness, prints the register and criteria, checks the saved prompt for the block and returns a
+marker plus the `whoami`/`session` commands. Its only write is that reimport. A failed prompt
+check exits 2, as with `checkpoint`.
+
+`close --handoff FILE --block ID --implementation STATE (--next-block ID|--final)` closes one: it
+saves the assigned continuation (or clears it with `--final`), runs the checkpoint and refreshes
+usage, then lists what remains manual. Exactly one continuation form is required. Steps run in that
+order and stop at the first failure, naming what was already applied: each underlying command keeps
+its own atomicity, the composition does not add a transaction. It never passes
+`--coverage-confirmed`, never records acceptance and never infers `--claim`.
+
+`whoami --provider codex|claude --nonce TOKEN [--project DIR --root DIR]` returns the session whose
+log contains a marker that session emitted, and only when exactly one log matches. Zero matches
+means the transcript has not been written yet: repeat it in a later call. `--project` narrows the
+candidates to the logs recorded in that directory before they are counted, since it is a declared
+constraint; if it leaves several, or none where the marker was found elsewhere, that is an error.
+No fallback selects a log by recency.
+
+`discover --provider codex|claude --project DIR` lists native IDs and log paths using metadata only.
+Without `--root` the search starts at the CLI home named by `CODEX_HOME`
+or `CLAUDE_CONFIG_DIR`, otherwise the default one. Optional `--root DIR` supports other machines
+and CLI homes; `--limit N` defaults to 20. Discovery never assigns a log to a task. It only reads
+a metadata prefix and may omit files without metadata there.
+
+`session --run FILE --provider codex|claude --id NATIVE_ID --log FILE --phase PHASE` registers and
+imports one explicitly selected log. Phases: exploration, specification, planning, implementation,
+verification, correction. The registration rejects a native ID not present in the source.
+
+Use `--from ISO --to ISO` to delimit mixed/resumed histories; from is inclusive and to exclusive.
+Do not reuse the same native session for multiple phases in one run: assign its main phase or use
+separate sessions. A session must not be attributed to several tasks without disjoint bounds.
+The comparison warns when native identities are reused across runs.
+
+For a child with its own native session ID, add `--parent provider:session-id --parent-evidence TEXT`.
+For Claude logs sharing the root session ID, also use `--agent ID`; that agentId must occur in the
+log. Parent evidence records the actual native invocation/metadata relationship, not an assumption.
+Missing or unidentifiable child logs leave coverage incomplete. Native formats lacking these fields
+are not silently inferred from filenames. Counts duplicated across registered logs are flagged.
+
+Optional `session --configuration ID` associates a previously captured configuration explicitly.
+Existing sessions can be linked with `session-config`; never infer attribution from the latest snapshot.
+See [persistent task commands](workflow-contract.md) for bind, checkpoint, next-prompt and configuration.
+`next-prompt --save` persists the assigned prompt in STATE and checks the write; `--check` checks
+without writing, `--clear` removes the obsolete generated section. At handoff use
+`checkpoint --next-block ID` to check persistence separately from technical verification.
+
+`--coverage-confirmed` is an operator attestation that the source contains only this task/range,
+all attributable subagents are included, and the source has been flushed. It is not a parser repair.
+Set it only after checking scope. The reimport after closure happens in the next session's `open`,
+or explicitly with `collect --run FILE`.
+If initially left unconfirmed, `collect --run FILE --coverage-confirmed` attests coverage for all
+registered sources after reviewing them; parser warnings are still retained.
+The agent refreshes registered logs through `open` at the next block entry and runs collect/report
+at closure. The last response's usage remains pending until a later observer can refresh the log.
+A different conversation starting does not prove an earlier conversation has ended.
+Repeated imports replace prior snapshots and are idempotent. A failed import does not partially
+update a run. One writer per manifest: a leftover `.lock` after a crash needs operator inspection
+before removal; never remove the lock of a live writer.
+
+## Token semantics
+
+| Source | Accounting |
+|---|---|
+| Codex event_msg/token_count | Differences between consecutive total_token_usage counters; duplicates contribute zero |
+| Claude message.usage | One message ID counted once; stream fragments consolidate growing output counts |
+| Skill loading | Skill tool calls and typed slash commands, recorded separately; a command name may be a CLI built-in |
+
+Codex input already includes cached input; reasoning is a detail of output. Neither is added again.
+Claude normalized input is input_tokens + cache_read_input_tokens + cache_creation_input_tokens.
+Normalized total is input plus output. Preserve numeric native counts separately. Missing categories
+are null, not guessed zero. Do not sum native snapshots and normalized totals together.
+
+A Codex counter decrease indicates a gap/reset and makes coverage partial. A bounded import needs
+a preceding counter; otherwise the first in-range total is omitted with a warning. Full-history
+imports require review for fork prefixes and unrelated earlier work. A Claude request straddling
+a time boundary is omitted as ambiguous. Unknown formats and partial lines produce warnings.
+
+These are **observed local log adapters**, with read-only smoke checks on Codex 0.153.4 and Claude
+Code 2.1.237 logs, plus synthetic tests (the installed Claude CLI reports 2.1.266).
+They are not a guaranteed stable vendor API. Record actual CLI versions,
+models and effort when present; unknown metadata remains explicit. Add format tests before expanding
+support. Structured programmatic alternatives are documented by
+[Codex](https://learn.chatgpt.com/docs/non-interactive-mode) and
+[Claude](https://code.claude.com/docs/en/agent-sdk/cost-tracking).
+[Claude monitoring](https://code.claude.com/docs/en/monitoring-usage) is an optional future source;
+this version does not enable telemetry or alter CLI settings.
+
+## Evidence, review and report
+
+- `result --run FILE --criterion ID --status pass|fail|not-run --observation TEXT --evidence FILE`
+  records an actual observation. Pass/fail require an existing artifact, stored by path and hash.
+  `not-run` records a missing prerequisite without inventing evidence.
+- `review --run FILE --status accepted|reopened|pending --note TEXT` records explicit user feedback.
+  Reopening retains past evidence and requires new results after the reopening event.
+- `intervention --run FILE --kind clarification|correction|approval|environment --note TEXT`
+  records manual intervention; silence is not evidence of zero intervention effort.
+- `environment --run FILE --note TEXT` records inspected loaded skill paths/versions, model/effort,
+  global instructions, memory and environment differences. Updates append environmentHistory,
+  preserving a legacy note on first update; environmentReview remains the latest view.
+  A note cannot prove isolation by itself.
+- `report --run FILE` writes report.md and report.json beside the manifest. Each session's usage is
+  marked final, stale or unavailable by rehashing its log, so a missing collect is visible.
+- `compare --runs FILE,FILE [--out JSON]` compares runs, retaining unsuccessful outcomes and warnings.
+
+Manifest schemaVersion 1 stores task/variant/project, fixed criteria, sessions, metric snapshots,
+append-only evidence/history/interventions and user review. Local manifests include native log paths;
+do not commit or share them without reviewing metadata. No message bodies or credentials are exported.
+The report's observed duration is the span of token events, not wall time since launch or active work.
+
+Verified means all required criteria have passing evidence. It is distinct from user acceptance.
+Artifact hash changes invalidate evidence. Controlled cases also invalidate verification if source
+files change after evaluation. For ordinary project tasks the operator must reopen/reverify after
+code changes; v1 does not fingerprint arbitrary large repositories automatically.
+
+Quality precedes token comparisons. Keep exploration costs separate and visible in project totals;
+do not hide them or count them once per downstream task. Compare variants within one provider/model
+configuration first. Different tokenizers, hidden subagents, cache state and human interventions
+can confound cross-provider comparisons. A single matched pair does not establish statistical benefit.
+
+## Prepared cases
+
+`prepare --out DIR --case order-filter|order-summary --variant baseline|candidate --provider codex|claude`
+creates a workspace, identical decided handoff, fixed criteria, installed applicable skills,
+PROMPT.md, OPERATOR.md and run.json. Baseline additionally requires `--baseline MANIFEST` pointing to
+the immutable original snapshot. Candidate uses sibling skill folders in the installed bundle.
+
+Only the three original skill responsibilities are installed in controlled workspaces; the benchmark
+tool/evaluator and reference solutions stay outside. Run `evaluate --run FILE` externally after work.
+Before launching any model, initialize Git inside the prepared workspace and verify that
+`git rev-parse --show-toplevel` resolves to that workspace, not the enclosing toolkit repository.
+The evaluator is procedural separation, not a hostile-code sandbox. Protected file changes block CLI
+evaluation. Do not inspect the evaluator during a model run or treat a contaminated run as controlled.
+
+Exit codes: 0 success (including reports/read-only blocked checkpoints), 1 invalid input/tool failure,
+2 a contradictory checkpoint --claim, a failed continuation check (`next-prompt --check` or
+`checkpoint --next-block`), or fixed acceptance
+failure from CLI evaluate. A successful report command is not a successful task.