@selesai/code 0.9.11 → 0.9.12

package/dist/skills/unlazy/references/parallel.md

@@ -0,0 +1,123 @@
+# Parallel pipelines and leaves
+
+Scopes and ownership leases coordinate cooperating unlazy processes. They prevent accidental cross-certification and refuse declared ownership overlap. They do not sandbox shell commands, enforce operating-system permissions, or stop a process that ignores the protocol from writing any file.
+
+## Layout
+
+```text
+.unlazy/
+  <scope>/
+    PLAN.md
+    GATES.md
+    gates/
+      leaf-*.md
+      node-*.md
+    status.log
+    session
+    hook-state.json
+  locks/
+```
+
+Keep `.unlazy/` untracked. The legacy single-pipeline layout, `GATES.md` plus `gates/*.md` at the project root, remains available for solo work.
+
+## Scope resolution
+
+A scoped checker invocation selects one pipeline in this order:
+
+1. `--scope <id>`
+2. `UNLAZY_SCOPE`
+3. the only scope present
+4. the legacy layout when no scoped pipeline exists
+
+The Stop hook can additionally use the current Claude Code `session_id` binding written by `--bind`. A binding associates a session with a scope; it is not authentication.
+
+When several scopes exist and none resolves, the checker refuses instead of running every ledger. The Stop hook allows the stop with a diagnostic instead of blocking a session on an unknown pipeline.
+
+Use scope ids that match `[A-Za-z0-9][A-Za-z0-9._-]{0,63}` and are not `.` or `..`. Do not use separators, traversal, or absolute paths.
+
+## What a scope isolates
+
+A scope limits unlazy's own:
+
+- default gate discovery
+- status log target
+- Stop-hook resolution and progress state
+- lease owner label
+
+A scope does not limit a `CHECK:` process. Checks inherit ambient operating-system access and can read or write outside the scope. Use separate worktrees or stronger process isolation when commands themselves must be isolated.
+
+## Ownership declarations
+
+Declare repository-relative paths before the first gate:
+
+```markdown
+OWNS: src/api/**, tests/api/**
+```
+
+Reject absolute paths and any path containing a `..` traversal segment. Every leaf dispatched concurrently must declare all paths it may modify and claim them before work:
+
+```text
+node <skill-dir>/scripts/gate-check.mjs --scope api --leaf leaf-1.2.1 --claim
+```
+
+Claiming checks all existing leases and writes the new lease while holding one global lease lock. Two simultaneous conflicting claims cannot both succeed. A claim is all-or-nothing.
+
+A scope/leaf label is itself exclusive while its lease exists. Repeating the same claim is refused; release that exact leaf before claiming it again. This prevents two workers dispatched with the same logical identity from both believing they own one lease.
+
+Lock directories contain JSON owner metadata. Unlazy deliberately does not auto-break an apparently stale lock, because deleting a live owner's path can let two successors enter at once. If a process dies while holding a lock, first verify that its recorded process is no longer running and that no unlazy operation could still own the lock, then remove only that specific abandoned lock manually. Never clear the whole lock directory while work is active. Approval-record locks use the same recovery rule.
+
+Overlap detection is deliberately conservative. It may reject two globs that a full intersection engine could prove disjoint, especially globs with mid-segment wildcards. It must not clear an uncertain pair as safe. Treat over-conflict as a prompt to use simpler disjoint paths or sequential dispatch.
+
+Examples:
+
+| First declaration | Second declaration | Result |
+|---|---|---|
+| `src/api/**` | `src/web/**` | disjoint |
+| `src/shared/**` | `src/shared/util.mjs` | conflict |
+| `src/a*.mjs` | `src/ab*.mjs` | conflict because intersection is possible |
+| `**` | `docs/**` | conflict |
+
+Leases cover only declared paths and only participants that honor them. They are coordination records, not write isolation.
+
+Release a leaf or whole scope after parent verification:
+
+```text
+node <skill-dir>/scripts/gate-check.mjs --scope api --release --leaf leaf-1.2.1
+node <skill-dir>/scripts/gate-check.mjs --scope api --release
+```
+
+An unknown `--leaf` is an error. The checker never silently falls back to the first ledger.
+
+## Concurrent ledger updates
+
+The checker serializes each gate-file update and commits it atomically. Before applying a completed check, it re-reads the ledger and confirms that the gate id and oracle fields still match what ran. If the command, expectation, working directory, or other bound oracle field changed in flight, the stale result is discarded.
+
+Preserve the ledger's original LF or CRLF style. Insert a missing evidence line without changing unrelated content. Keep result output deterministic in gate order even when `--jobs <N>` executes checks concurrently.
+
+The status log is append-only:
+
+```text
+node <skill-dir>/scripts/gate-check.mjs --scope api --log "leaf-1.2.1 verified"
+```
+
+Append-only logging reduces lost updates; it does not replace the live state fields in `PLAN.md`.
+
+## Session-keyed hook state
+
+The Stop hook keys progress state to the resolved scope and current session. Concurrent hook calls serialize their state update. Completion or disappearance of the ledger clears obsolete state. One session cannot consume another session's six no-progress blocks.
+
+The hook may be pinned with installer `--scope` or resolve a session binding written by:
+
+```text
+node <skill-dir>/scripts/gate-check.mjs --scope api --bind <session-id>
+```
+
+Do not treat a stored session id as a secret or identity proof.
+
+## Choose the right isolation level
+
+- Use one working tree and several scopes for read-heavy work or leaves with simple disjoint ownership.
+- Use one worktree per pipeline when worktree-local output or generated files would collide. Configure separate cache directories when cache writes can conflict; worktrees do not isolate external caches or services.
+- Use operating-system or container isolation for untrusted commands. Unlazy approval and leases are not a sandbox.
+
+Parallelism changes wall-clock time, not the evidence standard. Parent re-verification and branch integration remain required.

package/dist/skills/unlazy/references/token-economy.md

@@ -0,0 +1,39 @@
+# Token economy
+
+Spend model attention on implementation and judgment. Move repeated, deterministic verification into commands and keep orchestration context narrow.
+
+## Keep enforcement cheap
+
+- **Use runnable checks.** External command execution does not itself require model inference. The agent still spends context on the command, returned output, failure interpretation, and evidence review.
+- **Cap evidence.** Store resolved environment facts plus the automatic output fingerprint, never raw successful output or a full build log.
+- **Keep the Stop hook scan-only.** The hook itself does not call a model. A block causes another agent continuation, which does consume model work, so keep the six-block no-progress guard and make each block actionable.
+- **Use sequential checks by default.** Raise `--jobs` only for independent checks when wall-clock savings justify harder failure diagnosis.
+
+## Keep contexts focused
+
+- Give a leaf the shared contract and its own ledger, not the driver's transcript or unrelated leaf outputs.
+- Keep `SKILL.md` limited to the core workflow. Load method, gate, orchestration, and parallel references only when the selected mode needs them.
+- Append events to `status.log`. Do not repeatedly regenerate a large plan when one line records the event.
+- Keep failure logs local and summarize only non-sensitive decisive facts when a manual report needs them; automatic success evidence already contains a digest and byte count.
+
+## Spend stronger reasoning on leverage points
+
+Use the strongest available review for:
+
+- contracts and architecture
+- security and compatibility boundaries
+- branch integration
+- manual high-risk gates
+- parent re-verification and final claim audit
+
+Use lower-cost execution for mechanical transformations only after the pattern and acceptance gates are fixed.
+
+## Avoid false economy
+
+Do not save time by skipping approval, negative controls, parent re-verification, or integration gates. Those checks exist because a fast false completion costs more than a direct failure.
+
+Do not orchestrate a task that one focused session can implement and verify cleanly. Conversely, do not keep an entire build in one context merely to avoid subagent overhead when independent leaves and contracts are clear.
+
+## Measurement claims
+
+Earlier unlazy documentation gave exact token and effort ratios from a six-run exploratory comparison. The raw prompts, traces, outputs, and scoring records are not present in this repository, so those numbers are not reproducible here. Do not use them as product guarantees. A protocol for a future reproducible rerun is in [../research/validation-protocol.md](../research/validation-protocol.md).

package/dist/skills/unlazy/research/validation-protocol.md

@@ -0,0 +1,81 @@
+# Validation protocol and historical limitations
+
+## Status of the historical six-run comparison
+
+The v2 design was informed by a maintainer-run exploratory comparison described in earlier README versions:
+
+- two build tasks
+- three conditions per task: no skill, tree 3, and tree 6
+- one fresh folder and session per condition
+- independent review, adversarial verification, and browser testing
+
+Earlier documentation reported output-token ratios, self-found defect counts, one live failure, and report-number errors. This repository does not contain the exact prompts, model and harness versions, transcripts, token logs, output repositories, reviewer forms, browser recordings, or calculation code for those six runs. The reported numbers therefore cannot be independently reproduced or audited from source.
+
+Treat the historical comparison as design provenance only. It is too small for broad model claims and must not be described as proof that unlazy causes a specific improvement or cost multiplier.
+
+## Minimum protocol for a reproducible rerun
+
+### 1. Pre-register the comparison
+
+Record before execution:
+
+- exact unlazy commit and condition definitions
+- task prompts and any shared input assets
+- agent product, model id, model snapshot if exposed, reasoning setting, and permissions
+- operating system, runtime versions, browser, package manager, and network policy
+- timeout, retry, and failure-handling rules
+- metrics, scoring rubric, reviewer instructions, and exclusion criteria
+- randomization order and the planned number of independent repetitions
+
+Use more than one run per task and condition. A single run in each cell cannot distinguish the condition from run-to-run variation.
+
+### 2. Isolate each run
+
+Use a fresh session and fresh working copy for every run. Give each condition the same task body, tool access, time limits, and environment except for the intervention being tested. Do not let artifacts or reviewer notes from one run become visible to another.
+
+Archive:
+
+- the exact initial prompt and every follow-up
+- full agent and tool transcript
+- starting and ending repository commits
+- dependency manifests and lockfiles
+- test, lint, build, and browser logs
+- screenshots or recordings required by the rubric
+- token and timing data as exported by the harness
+
+Redact credentials without altering outcome-relevant content. Publish checksums for every archived artifact.
+
+### 3. Define metrics operationally
+
+Avoid labels such as "effort" unless tied to a measured proxy. Define each metric so another reviewer can calculate it from the archive.
+
+Suggested measures:
+
+- requested acceptance outcomes met before the final answer
+- placeholder or deferred-work occurrences under a fixed search rule
+- test, build, console, and browser failures
+- defects found and fixed before delivery, with duplicate-defect rules
+- false completion claims in the final report
+- incorrect numeric claims, compared with a scripted measurement
+- input, cached-input, and output tokens as reported by the same harness
+- elapsed wall-clock time, including retries
+
+Keep checkpoint success distinct from end-to-end task completion.
+
+### 4. Blind and duplicate review
+
+Remove condition labels from review artifacts where possible. Use at least two independent reviewers for subjective criteria. Record disagreements and a resolution rule. Do not tell reviewers the expected direction of the result.
+
+Run objective checks from scripts pinned in the archive. For a negative assertion, include a known positive control that proves the assertion can fail.
+
+### 5. Publish calculations
+
+Provide a machine-readable row per run and a script that regenerates every table and chart. Report raw counts alongside ratios, uncertainty, exclusions, and missing data. Keep exploratory findings separate from pre-registered outcomes.
+
+### 6. Bound the conclusion
+
+Describe results for the tested models, snapshots, tasks, and environments. Do not generalize a small coding comparison to all agents or all substantial work. Record failures and null results as carefully as improvements.
+
+## Repository-level validation
+
+The current implementation has a separate deterministic test suite for parser, checker, lease, hook, installer, and portability behavior. Run it with the repository's documented test command. Those software tests validate implementation behavior; they do not validate broad claims about model psychology or task productivity.

package/dist/skills/unlazy/scripts/dispatch-check.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Records and checks the all-starts-before-wait dispatch contract. Node 16+.
+
+import { resolve } from "node:path";
+import { getDispatchWave, updateDispatch } from "./lib/dispatch.mjs";
+
+const COMMANDS = new Set(["open", "start", "seal", "return", "abandon", "status"]);
+const args = process.argv.slice(2);
+
+function usage() {
+  return [
+    "Usage:",
+    "  dispatch-check.mjs open --scope ID --wave ID --leaf ID [--leaf ID ...] [--root PATH]",
+    "  dispatch-check.mjs start --scope ID --wave ID --leaf ID --handle OPAQUE_ID [--root PATH]",
+    "  dispatch-check.mjs seal --scope ID --wave ID [--root PATH]",
+    "  dispatch-check.mjs return --scope ID --wave ID --leaf ID [--root PATH]",
+    "  dispatch-check.mjs abandon --scope ID --wave ID --reason TEXT [--root PATH]",
+    "  dispatch-check.mjs status --scope ID --wave ID [--root PATH]",
+  ].join("\n");
+}
+
+function die(message) {
+  const safe = String(message).replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim().slice(0, 500);
+  console.error("unlazy dispatch: " + safe);
+  process.exit(2);
+}
+
+if (!args.length || args[0] === "--help" || args[0] === "-h") {
+  console.log(usage());
+  process.exit(args.length ? 0 : 2);
+}
+
+const command = args.shift();
+if (!COMMANDS.has(command)) die("unknown command " + command + "\n" + usage());
+
+const options = { root: process.cwd(), scope: null, wave: null, leaves: [], handle: null, reason: null };
+const single = new Set();
+while (args.length) {
+  const option = args.shift();
+  if (!["--root", "--scope", "--wave", "--leaf", "--handle", "--reason"].includes(option)) die("unknown option " + option);
+  if (!args.length || args[0].startsWith("--")) die(option + " requires a value");
+  const value = args.shift();
+  if (option === "--leaf") options.leaves.push(value);
+  else {
+    if (single.has(option)) die(option + " may be provided only once");
+    single.add(option);
+    options[option.slice(2)] = value;
+  }
+}
+
+if (!options.scope) die("--scope is required");
+if (!options.wave) die("--wave is required");
+options.root = resolve(options.root);
+
+if (command === "open") {
+  if (!options.leaves.length) die("open requires at least one --leaf");
+  if (options.handle !== null || options.reason !== null) die("open does not accept --handle or --reason");
+} else if (command === "start") {
+  if (options.leaves.length !== 1) die("start requires exactly one --leaf");
+  if (options.handle === null) die("start requires --handle");
+  if (options.reason !== null) die("start does not accept --reason");
+} else if (command === "return") {
+  if (options.leaves.length !== 1) die("return requires exactly one --leaf");
+  if (options.handle !== null || options.reason !== null) die("return does not accept --handle or --reason");
+} else if (command === "abandon") {
+  if (options.leaves.length || options.handle !== null) die("abandon does not accept --leaf or --handle");
+  if (options.reason === null || !options.reason.trim()) die("abandon requires --reason");
+} else if (options.leaves.length || options.handle !== null || options.reason !== null) {
+  die(command + " does not accept --leaf, --handle, or --reason");
+}
+
+const summary = (wave, id) => {
+  const started = Object.keys(wave.started).length;
+  const returned = Object.keys(wave.returned).length;
+  if (wave.state === "complete") return "COMPLETE " + id + " (" + returned + "/" + wave.leaves.length + " returned)";
+  if (wave.state === "abandoned") return "ABANDONED " + id + " (" + started + "/" + wave.leaves.length +
+    " started, " + returned + "/" + wave.leaves.length + " returned): " + wave.reason;
+  return wave.state.toUpperCase() + " " + id + " (" + started + "/" + wave.leaves.length +
+    " started, " + returned + "/" + wave.leaves.length + " returned)";
+};
+
+try {
+  if (command === "status") {
+    const wave = getDispatchWave(options.root, options.scope, options.wave);
+    console.log(summary(wave, options.wave));
+    process.exit(wave.state === "complete" ? 0 : 1);
+  }
+
+  const wave = await updateDispatch(options.root, {
+    action: command,
+    scope: options.scope,
+    wave: options.wave,
+    leaves: options.leaves,
+    leaf: options.leaves[0],
+    handle: options.handle,
+    reason: options.reason,
+  });
+  const started = Object.keys(wave.started).length;
+  const returned = Object.keys(wave.returned).length;
+  if (command === "open") console.log("OPEN " + options.wave + " (0/" + wave.leaves.length + " started, 0/" + wave.leaves.length + " returned)");
+  else if (command === "start") console.log("STARTED " + options.wave + " " + options.leaves[0] + " (" + started + "/" + wave.leaves.length + " started)");
+  else if (command === "seal") console.log("SEALED " + options.wave + " (" + started + "/" + wave.leaves.length + " started)");
+  else if (command === "abandon") console.log(summary(wave, options.wave));
+  else if (wave.state === "complete") console.log("COMPLETE " + options.wave + " (" + returned + "/" + wave.leaves.length + " returned)");
+  else console.log("RETURNED " + options.wave + " " + options.leaves[0] + " (" + returned + "/" + wave.leaves.length + " returned)");
+} catch (error) {
+  die(error.message);
+}