@cohortapp/agent-sdk 2.12.0 → 2.14.0

package/plugins/maestro-skills/vendor/unlazy/references/orchestration.md

@@ -0,0 +1,107 @@
+# Orchestrated mode
+
+Use orchestrated mode when one context cannot hold the task and its verification at full attention. Keep the driver responsible for planning, dispatch, independent verification, integration, and the root report.
+
+## Declare states and paths
+
+Use these leaf states only:
+
+- `WAITING`: one or more ids in `Needs` are not yet `VERIFIED`
+- `READY`: dependencies are verified and ownership is available
+- `IN-FLIGHT`: dispatched and not yet independently verified
+- `VERIFIED`: parent re-verification passed and manual gates were reviewed
+- `ABANDONED`: at least one required gate has a recorded handoff; never treat this as full completion
+
+Use `OPEN`, `VERIFIED`, or `ABANDONED` for branches. Store leaf ledgers as `gates/leaf-<id>.md` and integration ledgers as `gates/node-<id>.md`. Do not label a branch path as `leaf-*`.
+
+## Driver loop
+
+1. **Plan before fan-out.** Reread the original request and current amendments. Create `.unlazy/<scope>/PLAN.md`, `.unlazy/<scope>/GATES.md`, and one ledger per leaf and branch from the templates. Inventory every independently omittable outcome and acceptance-changing constraint with a stable id, owner, observing gate or manual review, disposition, and revision. Fix interfaces, naming, toolchain, dependencies, and exact ownership before dispatch.
+2. **Inspect and approve checks.** Run `gate-check --status` on every inherited ledger. Review each `CHECK:`, `EXPECT:`, and `CWD:`, including called scripts. Determine the shell and inherited `PATH`; a new oracle with no exact approval prints its resolved values during a normal run without executing. Use `--approve` only after inspection, and do not treat normal mode as a dry run once approval exists.
+3. **Claim every concurrent leaf.** Run:
+
+   ```text
+   node <skill-dir>/scripts/gate-check.mjs --scope <scope> --leaf leaf-1.2.1 --claim
+   ```
+
+   A refused claim means the split is not safe for concurrent dispatch. Change the plan or run the work sequentially; never bypass the refusal.
+4. **Launch each ready wave.** Give each leaf only the shared contract, its exact ownership and dependencies, its own ledger, and the four-pass completion rule. Open a dispatch wave for the independent `READY` leaves, call the host's native nonblocking launch once per leaf, record every host handle, and seal the wave before the first wait or result read. Follow [dispatch.md](dispatch.md); do not leak unrelated leaf histories.
+5. **Verify each return independently.** Record the native return in its wave, then re-run the returned leaf's runnable gates, including already checked gates:
+
+   ```text
+   node <skill-dir>/scripts/gate-check.mjs --root . --cwd . --reverify .unlazy/<scope>/gates/leaf-1.2.1.md
+   ```
+
+   `--status` alone is not re-verification. If an approved oracle changed, inspect it and approve the new oracle before continuing. Review manual gates directly and try to refute at least one passed gate.
+6. **Append status and roll forward.** Record the result without rewriting history:
+
+   ```text
+   node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.2.1 verified"
+   ```
+
+   Mark the leaf `VERIFIED`, release that exact leaf lease, and record the release before promotion:
+
+   ```text
+   node <skill-dir>/scripts/gate-check.mjs --scope <scope> --leaf leaf-1.2.1 --release
+   node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.2.1 lease released"
+   ```
+
+   Only then promote newly unblocked leaves from `WAITING` to `READY` and dispatch them without waiting for unrelated in-flight leaves.
+7. **Integrate bottom-up.** Work each `node-*.md` ledger only after all named children return. Reverify the children, then run interface, end-to-end, and regression checks.
+8. **Reconcile, release, and report.** Reread the current request and review every current contract row. Missing/stale ownership or observation, abandonment, deferment, and owner decisions are non-completion. Release the whole scope only after every leaf has settled, every dispatch wave is terminal, branch and root ledgers have been reverified, and final aggregate verification has run. Scope-wide release before that point is reserved for explicit recovery after verifying the recorded owner is gone, never normal promotion. Report only when both the inventory and root ledger are met, then remeasure every reported count.
+
+## Check concurrency
+
+Gate checks run sequentially by default (`--jobs 1`). This is the easiest transcript to debug and is the compatibility behavior.
+
+Use `--jobs <N>` only when runnable gates are independent and parallel execution reduces wall-clock time:
+
+```text
+node <skill-dir>/scripts/gate-check.mjs --root . --cwd . --reverify --jobs 4 .unlazy/<scope>/gates/leaf-1.1.1.md .unlazy/<scope>/gates/leaf-1.1.2.md
+```
+
+The limit is rolling: start another check when one finishes instead of waiting for a fixed batch. Output and file updates remain deterministic in ledger order. `--jobs` controls command execution, not subagent dispatch and not dependency readiness. Use [dispatch waves](dispatch.md) for native agent concurrency.
+
+## Rolling dispatch
+
+Treat dispatch as a loop:
+
+```text
+while an unverified leaf remains:
+  collect the independent READY leaves up to the host concurrency limit
+  open a dispatch wave for that exact set
+  launch every native agent and record every returned host handle
+  seal the wave before the first wait
+  wait for the next leaf to return
+  record that return in its dispatch wave
+  reverify that leaf and review its manual evidence
+  append status and mark it VERIFIED
+  release that exact leaf lease and record the release
+  promote each WAITING leaf whose Needs are all VERIFIED
+```
+
+Do not invent a dependency during dispatch. Add it to `PLAN.md`, correct the affected states, and record the change. A user amendment increments the contract revision and must be reconciled before more completion credit. Prefer independent leaves, but do not force independence where an interface must be established first.
+
+## Verification hierarchy
+
+1. **Leaf self-check:** catches ordinary incompleteness but remains self-certification.
+2. **Parent `--reverify`:** executes each runnable oracle again instead of trusting old or manually written evidence.
+3. **Branch integration:** catches locally correct children that do not compose.
+4. **Optional Stop hook:** blocks the driver from ending while its resolved pipeline has unmet ledgers or incomplete dispatch waves. It does not execute checks or validate their meaning.
+
+The parent must use the same required toolchain and declared shell. If the environment differs, record and resolve the mismatch instead of accepting old evidence.
+
+## Manual gates
+
+Automation cannot prove every user-facing or judgment-heavy outcome. For each manual gate:
+
+- cite the exact artifact, location, measurement, or reviewer decision
+- review consequences, not only visual polish
+- obtain independent review for high-risk outcomes when feasible
+- keep the gate unmet if evidence is ambiguous
+
+Do not call a leaf `VERIFIED` merely because every runnable gate passed.
+
+## When not to orchestrate
+
+Stay solo when one focused context can implement and verify the task without hiding independent deliverables. Orchestration has planning and integration overhead; use it for attention isolation, not ceremony.

package/plugins/maestro-skills/vendor/unlazy/references/parallel.md

@@ -0,0 +1,133 @@
+# 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 even when the replacement paths are disjoint, and the refused attempt never rewrites the original lease's OWNS path set. 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.
+
+After parent re-verification and manual review, release only that exact leaf and
+record the release before promoting any dependent:
+
+```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 --log "leaf-1.2.1 lease released"
+```
+
+Release the whole scope only after every leaf has settled, all dispatch waves
+are terminal, and branch, root, and final aggregate verification have run. The
+scope-wide form is otherwise only for explicit recovery after verifying the
+recorded owner is gone:
+
+```text
+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/plugins/maestro-skills/vendor/unlazy/references/token-economy.md

@@ -0,0 +1,48 @@
+# 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.
+
+## Mark leaf reasoning needs without inventing host controls
+
+`Tier` is planner metadata for execution leaves, not a model name or a routing
+guarantee:
+
+- Use `judgment` when the leaf's own artifact needs design, security or
+  compatibility reasoning, consequential manual review, or non-mechanical
+  verification.
+- Use `mechanical` only when the transformation pattern and acceptance gates are
+  already fixed.
+
+If the host exposes a documented model or reasoning control, the driver may map
+these tiers through that host-specific control at launch. If no such control is
+available, retain the tier as a briefing and review requirement and do not claim
+that a particular model or reasoning level was selected.
+
+Driver and branch duties are not leaf tiers. Contract and architecture work,
+dispatch decisions, parent re-verification, branch integration, and the final
+claim audit remain judgment responsibilities even when every execution leaf is
+mechanical.
+
+## 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/plugins/maestro-skills/vendor/unlazy/scripts/dispatch-check.mjs

@@ -0,0 +1,139 @@
+#!/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");
+}
+
+const UNSAFE_TERMINAL = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/;
+const TRUNCATION_MARKER = "...[truncated]";
+function terminalSafe(value, maxBytes = 500) {
+  const pieces = [];
+  const sizes = [];
+  let bytes = 0;
+  let truncated = false;
+  for (const character of String(value)) {
+    let piece = character;
+    if (UNSAFE_TERMINAL.test(character)) {
+      const code = character.codePointAt(0);
+      piece = code <= 0xff
+        ? "\\x" + code.toString(16).padStart(2, "0")
+        : "\\u" + code.toString(16).padStart(4, "0");
+    }
+    const size = Buffer.byteLength(piece, "utf8");
+    if (bytes + size > maxBytes) { truncated = true; break; }
+    pieces.push(piece);
+    sizes.push(size);
+    bytes += size;
+  }
+  if (!truncated) return pieces.join("");
+  const markerBytes = Buffer.byteLength(TRUNCATION_MARKER, "utf8");
+  while (pieces.length && bytes + markerBytes > maxBytes) {
+    pieces.pop();
+    bytes -= sizes.pop();
+  }
+  return pieces.join("") + TRUNCATION_MARKER;
+}
+
+function die(message, showUsage = false) {
+  console.error("unlazy dispatch: " + terminalSafe(message));
+  if (showUsage) console.error(usage());
+  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, true);
+
+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): " + terminalSafe(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, logWarning } = 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,
+  });
+  if (logWarning) console.error("unlazy dispatch: warning: " + terminalSafe(logWarning));
+  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);
+}