@deniscodp/skills 0.0.0-stage → 1.0.0

package/skills/denisco-handoff-implementation/references/delegated-implementation.md

@@ -0,0 +1,168 @@
+# Bounded implementation assignments
+
+Read this contract for an explicit bounded request or an assignment from an authorized
+`denisco-implementation-coordinator`. Direct "continue from B1" still continues through ready blocks.
+"Only B1 and B2, then return" stops after those blocks. A saved starting-block prompt does not
+override an explicit assignment boundary. This is a procedural boundary, not a filesystem sandbox.
+
+For a direct bounded user request, resolve the named blocks and stop at that boundary using the
+ordinary human-entry, question and persistence rules. Coordinator contact, coordination state and
+worker parentage below apply only when an authorized coordinator actually dispatched the work.
+
+## Assignment packet
+
+The coordinator supplies concrete values for:
+
+- Task and paths: worktree, handoff, PLAN, STATE, operational JSON, COORDINATOR and its history,
+  installed implementation skill. Coordination documents are read-only inputs for the worker.
+  The packet cites the history entries the worker needs; read those, not the whole history.
+- Authorization: user's coordination request, date/scope, current restrictions and permission list
+  location. Forward actual known answers and external changes; do not imply unanswered actions are done.
+- Assignment ID, attempt ID and kind: `implementation` or `integration`; ordered explicit block IDs, dependencies,
+  required criteria and any narrowed residual work. Expand ranges against PLAN, not numeric guesses.
+- Stop boundary: return after this assignment; checkpoint early for context pressure or a real blocker.
+  Implementation cannot move into unassigned blocks. Integration names checks and allowed corrections
+  across listed blocks; it does not authorize new product goals.
+- Profile and reading scope: requested effort; the HANDOFF points to read (the assigned points plus
+  the sections they cite); targeted checks, meaning browser checks of the assigned criteria and test
+  or build output read as summary and failures only; extra skills from the
+  operating guide's coordinated-workers section, or none.
+- Coordinator contact and question route; observable limits; measurement state preserved from the
+  sidecar. With enabled measurement include actual parent-attribution evidence when available,
+  never another session's registration ticket or ownership token.
+
+Example dispatch (substitute actual paths and recorded evidence):
+
+```text
+Use denisco-handoff-implementation at <installed-skill-path> and its bounded-assignment contract.
+Worktree: <absolute-project-path>. Task: <task-id>. Handoff: <absolute-HANDOFF>.
+Read <STATE>, <PLAN>, <operational-JSON>, <COORDINATOR> and the COORDINATOR-HISTORY entries
+<entry headings>; follow applicable project instructions.
+Authorization: <recorded user request/date and approved scope>; restrictions: <current limits>.
+Coordinator: <contact>. Assignment A2, attempt A2-1, kind implementation. Execute ONLY B3, B4, B5, B6 in
+dependency order. Required criteria and dependencies are in PLAN. Return after B6; do not start B7.
+Profile: light, effort medium. Read only HANDOFF points <P3-P6> and the sections they cite.
+Browser: targeted checks of the assigned criteria. Tests and builds: full output to a log file;
+read only the summary and the failures. Extra skills: <from the operating guide, or none>.
+Known user answers/changes: <recorded answers or none reported; pending actions stay pending>.
+Measurement: disabled. Acquire your own worktree claim; the coordinator has released its claim.
+If context pressure or a blocker prevents completion, checkpoint the residual work and return.
+Route questions to the coordinator. Update technical documents only through denisco-handoff-implementation;
+leave the coordination documents and packet files unchanged. Update STATE/STATE-HISTORY, save continuation,
+clean up owned resources, hand over any service that stays up with port and PID, release the claim
+and return the delivery defined by the bounded-assignment contract.
+```
+
+For integration replace the assignment line with the actual block IDs, cross-block checks,
+outstanding criteria and correction scope. Attach a saved prompt as background only when useful;
+the explicit bounded packet is the execution assignment, not the generic "continue from" text.
+
+## Worker entry and authority
+
+Read the applicable skills and assigned requirements in full, inspect repository evidence and
+acquire a new claim under [ownership](ownership.md). Record assignment/attempt IDs, actual observed
+worker identity and a link to COORDINATOR in STATE before application edits. If the prepared
+coordination assignment, technical documents and incoming packet conflict, ask the
+coordinator to reconcile before writing code. A prepared assignment without an active launch is
+not permission for an unrelated process to take it. Resumed by message after an external
+interruption, such as a usage limit or network error, recheck your claim with the ownership helper and continue from
+your last checkpoint within the same assignment.
+
+The programmer is the sole implementation owner: code, tests, HANDOFF, PLAN, STATE, STATE-HISTORY,
+sidecar and enabled measurement are its responsibility under the existing standard workflow.
+It updates STATE and appends its session entry to STATE-HISTORY, including when it is the final
+integration worker. HANDOFF/PLAN/map changes follow the existing split, new-point, new-goal and
+permission procedures; neither actor invents an alternative editing or approval path.
+The coordinator reads these documents but never edits them, even between workers. Conversely,
+the programmer never edits COORDINATOR or COORDINATOR-HISTORY, including for lifecycle bookkeeping.
+A visual-only child has a narrower artifact scope;
+do not confuse the two roles. The coordinator remains read-only while the programmer owns the worktree.
+Delegation does not expand the handoff permission list or bypass any always-ask action.
+
+Use the coordinator's recorded user updates instead of repeating human-entry questions. Send new
+questions to the coordinator, work on independent assigned portions and record returned answers.
+If communication is unavailable, save the question as a blocker and return rather than guess.
+A plan split may clarify work within this assignment; new block IDs or changes extending its scope
+require a revised coordinator assignment before execution. The worker does not dispatch its successor.
+
+## Verification roles and measurement
+
+The programmer performs ordinary denisco-visual-check captures and measurements as the implementation owner.
+It follows denisco-visual-check's principal responsibilities for source stability, index updates and cleanup;
+the restricted visual-child role applies only to a separately delegated visual-only checker.
+Use the runtime's available independent judge, or relay its blind packet through the coordinator
+when nested delegation is unavailable. The coordinator remains read-only during that relay.
+A relay is a pause, not a delivery: checkpoint STATE, keep the claim and owned services, and hand
+the coordinator the packet path marked as a relay request. It resumes this same worker with the
+verbatim observations; the worker saves them as evidence and applies the predeclared condition.
+Only when the runtime cannot resume the worker does the judgment become residual work in the
+ordinary delivery.
+
+With measurement enabled, native parentage remains factual: register the coordinator first, then
+the programmer as its actual child, and judges under their actual parent. A programmer's visual
+attempt uses `executor: subagent` with the coordinator as principal session when that is the native
+relationship; a genuinely top-level executor uses `principal`. The explicit coordination request
+includes the programmer's required checks. Reconcile future sidecar executor entries, preserving
+historical attempts. The owning programmer records its own results; the coordinator must not write
+the run concurrently. Missing native attribution/loading evidence stays pending, never relabeled
+to satisfy the checker. With measurement disabled none of this activates benchmark tooling.
+
+## Checkpoint and delivery
+
+After each block update evidence and STATE normally. Within a long block or residual, also refresh
+STATE after each verified correction or completed evidence run, so an interrupted attempt leaves a
+resumable record. At the assignment boundary, or an early return,
+finish applicable checks, preserve verification gaps, append a dated HISTORY entry and save the
+ordinary implementation continuation for remaining task work. Even after the last implementation
+block, retain a continuation anchored to that block while final integration remains; STATE names
+the integration work so a direct manual resume does not redo finished implementation.
+The coordinator owns group selection; a worker can propose the next step but cannot launch it.
+Clean up or explicitly hand over retained resources, drain children, finish state/measurement writes
+and release the claim before returning. A service that must stay up runs detached from you and is
+handed over with port and PID, because the coordinator closes you after delivery. A final message
+alone does not prove safe transfer.
+
+Return the delivery in the user's language with these headings, every time, in this order; write
+"unknown" or "none" rather than dropping a heading:
+
+1. **Outcome:** one line with assignment and attempt IDs, blocks, implementation/verification status
+   and whether useful progress occurred.
+2. **Blocks and criteria:** criterion results per block with evidence paths; verification gaps named.
+3. **Commits and changes:** commits, changed areas, relevant dirty files/user changes and any
+   invalidated earlier evidence.
+4. **Findings:** facts the coordinator or user should know, such as pre-existing defects or
+   technical choices recorded in PLAN.
+5. **Residual work and questions:** exact unfinished work, blockers/questions and dependency
+   readiness, including context-driven stops; the supported next step.
+6. **Your checks:** user verifications this work added to Your actions, with where and how.
+7. **Cleanup, services and claim:** resource/child cleanup, services handed over with port and PID,
+   ownership-release result, STATE/HISTORY paths and the saved continuation location.
+8. **Identity and configuration:** observed native worker identity; requested/observed model and
+   effort with sources or unknown values; fresh-context invocation evidence when available, never
+   an invented clear/reset.
+
+## Technical persistence and coordinator references
+
+Follow the existing session-plan contract for technical state and history. In STATE's Status keep
+only the coordination link, assignment/attempt reference, actual worker identity and scoped execution
+authorization alongside normal technical status. Put the programmer's work and evidence in its dated
+STATE-HISTORY entry. The session grouping, recovery allowance, lifecycle history and coordination
+launch/resume prompt belong in the coordinator-owned documents, never a second plan inside STATE.
+
+The coordinator writes its prepared attempt before launching, then stays read-only until return
+and verified handover. Its files may therefore lag a running worker. Persist the attempt identity
+in the technical record so recovery can correlate it with native invocation/peer evidence and the
+ownership claim. A prepared record or missing handle alone does not prove that no worker started.
+Return the actual evidence; the coordinator records it after reacquiring, with the recording time.
+
+For legacy Coordination notes in STATE, the coordinator imports supported facts into its own files
+without touching technical documents. During the next ordinary authorized worker update, archive
+the replaced notes unchanged in STATE-HISTORY and replace them with the short reference above.
+Preserve technical results, outstanding user actions, authorization, retry facts and source history;
+report conflicts to the coordinator before treating an old note as current. Do not erase old HISTORY
+entries or restart a worker because of a migration. If migration cannot run yet, keep it pending.
+
+The ordinary generated STATE prompt remains the direct implementation continuation. The separate
+coordinator prompt lives in COORDINATOR. Its presence never activates delegation on a direct request.
+The programmer clears only obsolete technical continuation prompts under the standard completion/stop
+rules; the coordinator clears its own prompts. Neither clears the other's document or pending evidence.

package/skills/denisco-handoff-implementation/references/ownership.md

@@ -0,0 +1,105 @@
+# One writer per worktree
+
+An assignment, native conversation ID, tracking ticket or saved continuation is not an execution
+claim. Two interactive processes can resume the same conversation. Treat each new CLI/process
+entry as a new execution instance even when its transcript contains an earlier claim token.
+Compaction within a demonstrably continuous instance does not require reacquiring; if continuity
+is uncertain, remain read-only and inspect the owner rather than adopting the transcript's token.
+
+## Enter and claim
+
+Before task writes (including PLAN/STATE, COORDINATOR and its history, sidecar, measurement registration, probes or builds),
+inspect the actual Git worktree, current task documents and available peer/process metadata.
+Distinguish top-level processes from explicitly delegated children using actual parent evidence;
+sharing a native session ID proves neither that they are one process nor that one is a child.
+Do not launch/resume a second implementation CLI to delegate a visual check.
+
+Use the installed [ownership helper](../scripts/ownership.mjs), with Node 20+ in an initialized
+Git worktree. It reads the `.git` directory/file directly and launches no subprocesses:
+
+```text
+node <denisco-handoff-implementation>/scripts/ownership.mjs status --worktree <directory>
+node <denisco-handoff-implementation>/scripts/ownership.mjs acquire --worktree <directory> --handoff <file> --block <B1-or-planning> --session <diagnostic-label>
+node <denisco-handoff-implementation>/scripts/ownership.mjs check --worktree <directory> --claim <returned-claimId>
+node <denisco-handoff-implementation>/scripts/ownership.mjs release --worktree <directory> --claim <returned-claimId>
+```
+
+The agent runs these commands and keeps tokens internal; never ask the user to assemble them.
+Acquisition creates `.agent/workflow-writer.json` at the real Git worktree root, independently of
+measurement. It claims the whole worktree, including shared task state and tooling, not just B1.
+Nested invocation paths resolve to the same root; separate Git worktrees have separate claims.
+When task documents and code live in different worktrees of one repository, claim each worktree
+you write and pass the same real HANDOFF to both acquisitions: the helper accepts a handoff in any
+worktree of the same repository and rejects one from another repository.
+Do not commit the local record. Existing task authorization permits this bookkeeping in writable
+mode; read-only/Plan Mode uses `status` and leaves acquisition pending.
+
+Acquire once on entry; only `acquired` permits writing. An existing claim always conflicts,
+including one with the same session label. `--session` is diagnostic, not an ownership key.
+Retain the newly returned claim ID only in the instance that acquired it; do not copy tokens from
+the owner file, inherited conversation, another instance or a continuation prompt to pass `check`.
+Recheck before each editing/verification phase and before shared state/register updates. Only
+`owned-by-caller` permits continued writes; missing/replaced claims stop them.
+
+This is a cooperative guard: it serializes claims, but cannot intercept arbitrary editor/shell
+writes or prove which process supplied a token. Peer inspection and adherence remain necessary,
+especially with older sessions that do not use the guard. A free claim does not make an observed
+active legacy writer safe. If the helper is unavailable or cannot establish the worktree, report
+that narrow blocker and continue read-only inspection, not unguarded implementation.
+
+## Conflict and transfer
+
+With another owner, keep this instance read-only: no probes/build outputs, `track`, `open`,
+`collect`, `result`, `close`, STATE updates or shared index edits. `open` is not read-only when
+measurement is enabled. Read existing documents, logs, artifacts and `checkpoint` output instead.
+Report the owner and evidence of activity without claiming an unknown process is a subagent.
+Do not kill/message peers without authorization, race their writes, or launch repeated watchers.
+
+Quiet files, elapsed time, an idle status, a final response, a shared session ID or a stale claim
+do not authorize takeover. The owner retains the claim until its writes and children have stopped,
+validation and state/report updates are finished, and it explicitly releases it. Release also on
+a deliberate pause after recording pending work and stopping/draining delegated tasks. A fresh
+entry then acquires a new claim, rereads current evidence and continues only unfinished authorized
+work. Parallel implementation belongs in separate worktrees with explicitly coordinated scope.
+
+After a crash, inspect the claim and establish that the previous writer and its children cannot
+continue (for example, verified process exit or an explicit coordinated stop). If uncertain, ask
+for that concrete coordination decision; do not expire a claim automatically. Only after that
+evidence may recovery release the observed claim using its exact ID, then acquire afresh. An old
+ID cannot release a replacement claim. A corrupt record or leftover short-lived `.lock` requires
+manual inspection under the same stopped-writer condition; never blindly delete either.
+
+## Sequential programming workers
+
+An explicitly authorized denisco-implementation-coordinator follows
+[bounded implementation](delegated-implementation.md). The coordinator may claim the worktree for
+preparation or bookkeeping between workers, then releases before launch. Its document writes are
+limited to COORDINATOR and COORDINATOR-HISTORY; holding the claim never permits technical-document
+edits. Ownership records and explicitly enabled measurement registration/reporting remain governed
+by their existing helpers. The programmer acquires its own new claim
+and owns code, verification, task documents and enabled measurement. During that assignment the
+coordinator remains read-only, including its own documents. The programmer also leaves the
+coordination documents unchanged: document authority does not transfer with the worktree claim.
+Neither actor passes a claim token to the other. After releasing to launch, the coordinator may not
+reacquire during the worker's startup window just to save its handle; defer recording until safe return.
+
+After a worker's final writes, cleanup and explicit release, verify its children and outstanding
+commands cannot continue writing before the coordinator or successor acquires. A missing claim
+alone does not prove all old processes stopped. Recovery after a crash uses the same verified
+stopped-writer rule above. A prepared assignment or an old worker handle never replaces this check.
+
+## Visual children and evidence
+
+The implementation owner retains ownership while delegating a visual-only check. A visual child receives criterion IDs, a
+baseline/post-edit role and an exclusive artifact directory; it never acquires/releases the
+principal claim, edits source/task documents/registers, or starts a second implementation CLI.
+The child returns exact artifacts, proposed index rows and skill-loading evidence. The principal
+merges the index and registers the child/results serially. Do not edit the measured source or
+shared capture tooling while a visual attempt is running; finish a baseline before source edits.
+
+On resume or transfer, read current STATE, the bound run's attempts/results, referenced artifacts
+and attributable child logs before declaring a check absent or scheduling a replacement. Match
+criterion, attempt, parent/child identity, explicit skill loading and the tested code/fixture.
+Distinguish absent evidence from evidence that exists but is unregistered, stale, failed or
+inconsistent. Reconcile a registration gap using existing evidence; rerun only when the evidence
+does not cover the current requirement/code. Preserve prior failures and explain any invalidation.

package/skills/denisco-handoff-implementation/references/session-plan.md

@@ -0,0 +1,195 @@
+# Session plan and persistent state
+
+Default: PLAN.md, STATE.md and STATE-HISTORY.md alongside the handoff. Honor project conventions
+and explicit paths. Create documents only in a mode that permits writing.
+
+## Group by coherence before difficulty
+
+1. Build the dependency graph. Resolve cycles as one coherent change or an explicit staged contract.
+2. Keep duplicated instances of the same rule together when intermediate divergence would be wrong.
+   This takes precedence over difficulty or file-count heuristics.
+3. Put shared contracts, pure rules and persistence before consumers; use verifiable blocks.
+4. Estimate context and verification effort. Colors explain difficulty, not fixed session counts.
+   Allow a small task in one session or multiple tightly related points.
+5. Work through the approved plan in dependency order. Work outside it follows the skill's split,
+   new-point and new-goal rules; finishing early does not authorize unrelated work.
+
+Record the split once; revisit when evidence changes dependencies, scope or feasibility. A revision
+rewrites PLAN and moves the replaced version to STATE-HISTORY.md.
+Parallel execution requires an explicit coordination decision: independent dependencies do not
+guarantee safe concurrent edits, fixtures or shared environments.
+Apply [worktree ownership](ownership.md) before any task write, including planning and accounting.
+A block assignment is not a claim; two processes can share a conversation ID. The worktree claim
+is separate from PLAN/STATE and measurement so disabled accounting cannot bypass coordination.
+
+## Operational JSON
+
+Append `.workflow.json` to the full handoff filename, including its `.md` extension.
+This file carries structure and links, not a second copy of criterion outcomes:
+
+```json
+{
+  "schemaVersion": 1,
+  "taskId": "feature-example",
+  "handoff": "HANDOFF.md",
+  "plan": "PLAN.md",
+  "state": "STATE.md",
+  "measurement": { "status": "disabled" },
+  "blocks": [
+    { "id": "B1", "points": ["P1"], "dependsOn": [], "criteria": ["P1-A1", "P1-A2"] },
+    { "id": "B2", "points": ["P2"], "dependsOn": ["B1"], "criteria": ["P2-A1"] }
+  ]
+}
+```
+
+Resolve document paths relative to the JSON. During specification `blocks` may be empty.
+Before executing a block, reconcile the complete planned map with the handoff, including blocked
+criteria and those the user verifies. A script cannot detect a criterion never supplied or assigned
+to the wrong block. Blockers, permissions and Your actions live in the Markdown documents, not here.
+
+Measurement is `unknown`, `disabled`, or `enabled`. Default to `disabled` unless the current user
+request or applicable project instructions explicitly activate workflow measurement for this task.
+Recover legacy context only from referenced documents. Disabled is authoritative across sessions:
+do not load, install or invoke denisco-workflow-benchmark, search for a run, or rewrite it to unknown/enabled.
+Unknown is inert legacy or interrupted explicit setup, never an active default; preserve it or resolve
+it to disabled unless explicit activation evidence exists. Do not invent another run. In Plan Mode
+propose the JSON for the writable phase. Missing helpers are not a product-evidence limitation when
+measurement is inactive.
+
+When enabled, denisco-workflow-benchmark `bind --run <file> --handoff <file>` populates measurement with
+`status`, absolute `run`, `runId`, benchmark `taskId`, and `criteriaHash`. Use the command rather
+than inventing the hash. Project and benchmark task IDs may differ: preserve both explicitly.
+Stale/moved bindings require review, not guessing. The detailed CLI belongs to denisco-workflow-benchmark.
+
+Measured criterion outcomes/history belong in the run; STATE.md explains them. Without measurement,
+STATE.md is the evidence record and automated checks cover only structure and links.
+
+## PLAN.md
+
+First entry may have only HANDOFF and an empty operational map. Register the planning conversation
+through track after setup. A handoff-only request is planning-only: create/reconcile PLAN, STATE,
+the complete planned block map and a saved/checked first execution prompt, then choose the
+coordinated or direct execution path and reach its start question. Preserve an existing split and
+observed progress when repairing partial documents.
+
+PLAN is the block map, rewritten when the plan changes:
+
+- Task ID, handoff link, **Done when** from the handoff and the plan date.
+- Table: block ID, point IDs, purpose, dependencies (blocks and your-action items) and verification.
+- Final integration checks and excluded points with reasons.
+- Operational JSON link and complete planned block/criterion map. The map describes the plan,
+  not permission to execute it.
+
+Resolve every unresolved blocker before delivering a runnable assignment. Choose the first
+dependency-ready block; if every block waits on a your-action item or a third party, say so in
+STATE, fill Your actions and stop without the start question. In Plan Mode present all planning
+deliverables, including the first execution prompt. Once writing is allowed, persist them and ask.
+A private CLI plan does not substitute for these documents or change this phase boundary.
+
+## STATE.md
+
+STATE is the current picture, rewritten each session and readable in about two minutes (about
+100-150 lines). Its sections, in this order:
+
+1. **Your actions:** each item says what to do, where, which point it unblocks and how the agent
+   will check it. Done items leave the list. An empty list reads "Nothing needed from you."
+2. **Status:** task ID, links to HANDOFF, PLAN and STATE-HISTORY, last update; branch, commit and
+   relevant uncommitted files, distinguishing user changes; the current phase and the user
+   instruction that started it, with date and scope. Tool permissions and document existence alone
+   never establish that instruction.
+3. **Points and criteria:** point status (planned, in-progress, implemented-unverified, verified or
+   blocked); per criterion pass/fail/not-run, observation, evidence path and verifier.
+4. **Blockers:** each pending question or wait, and what it stops.
+5. **Next step:** the next block, or why the session stopped.
+6. The saved next-session prompt in its generated section, while task work remains.
+
+For coordinated execution the programmer adds a link to COORDINATOR and the current assignment/attempt
+reference in Status, following [bounded implementation](delegated-implementation.md). The session
+plan, coordination history and coordinator resume prompt live in COORDINATOR.md and
+COORDINATOR-HISTORY.md beside STATE by default. Only the coordinator writes those files; only the
+programmer updates the technical documents through this existing workflow. No sidecar schema change.
+
+Mention worktree ownership only for a conflict or a handover between runtimes; the live ownership
+record arbitrates writers, and claim tokens never go into STATE or the next prompt. Mention
+measurement only while it is enabled.
+
+## STATE-HISTORY.md
+
+Append-only, beside STATE. Each session adds one dated entry: work done, answers and decisions
+received, evidence paths, reopenings, and any text replaced in HANDOFF, PLAN or STATE. Nothing is
+deleted from it. In coordinated mode each programmer, including final integration, writes its own
+technical session entry; the coordinator writes only COORDINATOR-HISTORY. Read it when the current picture is not enough: an audit, a reopening or a
+disputed result.
+
+A STATE written before this format: move it unchanged into STATE-HISTORY.md as the first entry,
+then write a new STATE from it. Carry every open criterion, blocker and pending user action into
+the new STATE.
+
+Never erase previous results: a result replaced in STATE moves to STATE-HISTORY.md. Never mark a
+point verified because code exists or an agent said done. Reconcile stale state with the repository
+on resume and before delivery. Replace obsolete current claims such as execution pending or no
+checks run after the user has launched implementation. Read current run attempts, result artifacts
+and attributable child logs before declaring delegated verification absent. Existing but
+unregistered evidence needs attribution/registration repair, not an automatic new model run.
+With finished code and required verification gaps use `implemented-unverified`, never
+`verified except A5`. Keep implementation, verification, accounting and user acceptance distinct.
+
+Only when measurement is explicitly enabled, register through `track` and its returned nextCall,
+then use `open --handoff <file> --block <B1>` after the block map exists. Keep session keys and
+tickets internal. After each block's final validation, record measured evidence with `result`,
+update STATE and run the read-only `checkpoint` for that block. When the session stops, close with
+`close --handoff <file> --block <last-block> --implementation <state>
+(--next-block <B2> | --final) --claim <proposed-status>`, which saves or clears the continuation
+and runs the checkpoint. The equivalent separate commands remain available:
+`next-prompt --handoff <file> --block <B2> --save` followed by
+`checkpoint --handoff <file> --block <B1> --implementation complete --claim <proposed-status>
+--next-block <B2>`. A contradicting claim or missing/stale saved prompt returns code 2 and
+the computed status. Add `--session-key provider:id` only when identified and `--session-state active`
+while work is live. Missing registration is reported separately from technical verification.
+Reconcile STATE.md and the final response with the output; technical status and continuation
+delivery are separate. The checker verifies the generated section, not claims in free prose.
+If code or evidence changes after this check, refresh evidence/results and repeat the checkpoint.
+Review evidence relevance yourself: a matching hash is not semantic proof of an acceptance criterion.
+
+## Next-session prompt
+
+```text
+Use denisco-handoff-implementation to continue task <task-id> (<HANDOFF.md>) from block <B2>.
+Read <STATE.md> first: Your actions, pending blockers and the next step are there.
+Plan: <PLAN.md>. Operational context: <absolute handoff-path.workflow.json>.
+Measurement: disabled.
+```
+
+Everything else the next session needs lives in STATE and in this skill: ownership, evidence
+reconciliation, permissions and authorization rules are not repeated in the prompt. If those files
+cannot be located, supply actual content instead of pretending they exist. Only an explicit
+measurement activation replaces the inactive measurement line with the denisco-workflow-benchmark
+registration, open, close and internal ticket instructions from this skill and the benchmark
+contract.
+
+When measurement is explicitly enabled and the helper is available, use denisco-workflow-benchmark
+`next-prompt --handoff <file> --block <B2> --save` for the
+proposed next assignment; the helper resolves STATE from the operational JSON and verifies its write.
+`--check` checks the saved prompt without writing. Without either option the command only prints:
+printing does not satisfy persistence. `--save`, `--check` and `--clear` are mutually exclusive.
+
+The helper owns only the section between `<!-- workflow:next-prompt:start -->` and
+`<!-- workflow:next-prompt:end -->`. Keep everything else outside it; do not manually customize
+the generated text. A first save adds the section without removing legacy prose: reconcile any
+obsolete manual prompt yourself, moving it to STATE-HISTORY.md. Duplicate or damaged markers
+require repair, not a second generated section.
+
+The next block is explicit, never picked by the generator. Use the same block for unfinished
+implementation or verification. A subsequent user request launches that prompt. An explicitly
+authorized denisco-implementation-coordinator instead dispatches a bounded packet; its block list and stop
+boundary take precedence over the generic starting-block prompt. Keep the coordinator launch/resume
+prompt in COORDINATOR; STATE keeps its technical continuation and short coordination reference.
+No generator change or manual alteration of generated text is needed.
+Clear it only when no task work remains, or the user ends the task or asks for no prompt; a user
+stop with work remaining keeps it. Preserve pending acceptance/accounting.
+Measurement disabled uses the template directly. For legacy `unknown`, replace only the status and
+say that it remains inactive without a current explicit activation. Save and reread the prompt
+manually without loading or installing denisco-workflow-benchmark. Automated benchmark acceptance and prompt
+checking are intentionally inactive. In Plan Mode
+propose changes and identify the pending write. Link STATE in the final response and copy only
+its actual saved prompt if also displaying it in chat.

package/skills/denisco-handoff-implementation/scripts/ownership.mjs

@@ -0,0 +1,153 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+// Cooperative worktree ownership, independent of conversation IDs and measurement.
+// This guards claims, not arbitrary editor/shell writes. Never expire claims by age.
+function noSymlinks(file) {
+  let current = path.resolve(file);
+  for (;;) {
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) throw new Error(`Symlink ownership path: ${current}`);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+
+function gitRoot(directory) {
+  // Read standard Git markers directly: the guard must also work where subprocesses are denied.
+  // Native realpath expands Windows 8.3 aliases before comparing root and handoff paths.
+  let root = fs.realpathSync.native(path.resolve(directory));
+  if (!fs.statSync(root).isDirectory()) throw new Error('Worktree must be a directory');
+  for (;;) {
+    const marker = path.join(root, '.git');
+    let stat;
+    try { stat = fs.statSync(marker); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (stat) {
+      let gitDir = marker;
+      if (stat.isFile()) {
+        const match = /^gitdir: (.+)\r?\n?$/.exec(fs.readFileSync(marker, 'utf8').trimEnd());
+        if (!match) throw new Error('Invalid Git worktree marker; inspect before claiming');
+        gitDir = path.resolve(root, match[1]);
+      } else if (!stat.isDirectory()) throw new Error('Invalid Git worktree marker');
+      if (!fs.statSync(path.join(gitDir, 'HEAD')).isFile()) throw new Error('Invalid Git worktree HEAD');
+      return { root, gitDir };
+    }
+    const parent = path.dirname(root);
+    if (parent === root) throw new Error('Ownership requires an initialized Git worktree; verify its root before writing');
+    root = parent;
+  }
+}
+
+// Linked worktrees of one repository share its common Git directory. Task documents can then live
+// in one checkout (often the main one) while the code is written in another.
+function commonDir(gitDir) {
+  const pointer = path.join(gitDir, 'commondir');
+  const common = fs.existsSync(pointer) ? path.resolve(gitDir, fs.readFileSync(pointer, 'utf8').trim()) : gitDir;
+  return fs.realpathSync.native(common);
+}
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+function sameRepository(loc, file) {
+  let other;
+  try { other = gitRoot(path.dirname(file)); } catch { return false; }
+  return samePath(commonDir(loc.gitDir), commonDir(other.gitDir));
+}
+
+function location(worktree) {
+  if (!worktree) throw new Error('Provide --worktree DIR');
+  const { root, gitDir } = gitRoot(worktree);
+  const dir = path.join(root, '.agent');
+  const file = path.join(dir, 'workflow-writer.json');
+  const lock = `${file}.lock`;
+  noSymlinks(file); noSymlinks(lock);
+  return { root, gitDir, dir, file, lock };
+}
+
+function readOwner(file, root) {
+  let data;
+  try { data = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error('Unreadable ownership record; inspect without replacing it');
+  }
+  const sameRoot = typeof data?.worktree === 'string' && samePath(data.worktree, root);
+  if (data?.schemaVersion !== 1 || !sameRoot || typeof data.claimId !== 'string'
+      || !/^[a-f0-9-]{36}$/.test(data.claimId) || typeof data.handoff !== 'string') {
+    throw new Error('Invalid ownership record; inspect without replacing it');
+  }
+  return data;
+}
+
+export function ownership({ action, worktree, handoff, block = 'planning', session, claim } = {}) {
+  if (!['status', 'acquire', 'check', 'release'].includes(action)) throw new Error('Use status|acquire|check|release');
+  if (action === 'acquire' && claim) throw new Error('Acquire always creates a new claim; never reuse an old token');
+  if (['check', 'release'].includes(action) && !claim) throw new Error('Provide the current execution instance\'s --claim TOKEN');
+  const loc = location(worktree);
+  let target;
+  if (action === 'acquire') {
+    if (!handoff) throw new Error('Provide --handoff FILE');
+    target = fs.realpathSync.native(path.resolve(handoff));
+    const relative = path.relative(loc.root, target);
+    const inside = relative && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    if (!fs.statSync(target).isFile() || (!inside && !sameRepository(loc, target))) {
+      throw new Error('Handoff must be a file inside this worktree or another worktree of the same repository');
+    }
+    if (typeof block !== 'string' || !block.trim()) throw new Error('Provide a block or planning label');
+  }
+  const inspect = () => {
+    const owner = readOwner(loc.file, loc.root);
+    if (action === 'status') return { status: owner ? 'owned' : 'unclaimed', owner, file: loc.file };
+    if (action === 'check') return { status: owner?.claimId === claim ? 'owned-by-caller' : 'conflict', owner, file: loc.file };
+    if (action === 'acquire') {
+      // Deliberately non-reentrant: a duplicate resume can share session metadata.
+      if (owner) return { status: 'conflict', owner, file: loc.file };
+      const next = { schemaVersion: 1, claimId: crypto.randomUUID(), worktree: loc.root,
+        handoff: target, block, session: session ?? null, acquiredAt: new Date().toISOString() };
+      fs.writeFileSync(loc.file, `${JSON.stringify(next, null, 2)}\n`, { flag: 'wx' });
+      return { status: 'acquired', owner: next, file: loc.file };
+    }
+    if (owner?.claimId !== claim) return { status: 'conflict', owner, file: loc.file };
+    fs.unlinkSync(loc.file);
+    return { status: 'released', claimId: claim, file: loc.file };
+  };
+  if (['status', 'check'].includes(action)) {
+    if (fs.existsSync(loc.lock)) return { status: 'busy', file: loc.file };
+    const result = inspect();
+    if (fs.existsSync(loc.lock)) return { status: 'busy', file: loc.file };
+    return result;
+  }
+  fs.mkdirSync(loc.dir, { recursive: true });
+  noSymlinks(loc.file); noSymlinks(loc.lock);
+  let fd;
+  try { fd = fs.openSync(loc.lock, 'wx'); }
+  catch (error) {
+    if (error.code === 'EEXIST') return { status: 'busy', file: loc.file };
+    throw error;
+  }
+  try { return inspect(); }
+  finally { fs.closeSync(fd); fs.unlinkSync(loc.lock); }
+}
+
+const usage = 'node ownership.mjs status|acquire|check|release --worktree DIR [--handoff FILE --block ID --session LABEL] [--claim TOKEN]';
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const [action, ...args] = process.argv.slice(2);
+    if (action === 'help' || !action) { console.log(usage); }
+    else {
+      const options = { action };
+      for (let i = 0; i < args.length; i += 2) {
+        const key = args[i].slice(2);
+        if (!args[i].startsWith('--') || !['worktree', 'handoff', 'block', 'session', 'claim'].includes(key)
+            || !args[i + 1] || args[i + 1].startsWith('--') || Object.hasOwn(options, key)) throw new Error(usage);
+        options[key] = args[i + 1];
+      }
+      const result = ownership(options);
+      console.log(JSON.stringify(result, null, 2));
+      if (['conflict', 'busy'].includes(result.status)) process.exitCode = 2;
+    }
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}