unlazy

Completion discipline for substantial AI-agent work, backed by runnable gates.

Write the acceptance ledger first. Execute reviewed checks. Reverify returned work. Report only what the evidence supports.

Quick start | Gate contract | Orchestration | Security | Research

Version status

The current source targets 2.1.0. It is not identified here as a tagged GitHub release. Pin an exact commit when you need an immutable installation. See CHANGELOG.md for the unreleased change set.

Install

Use the skills CLI for supported agents:

npx skills add Leonxlnx/unlazy

Add -g for a user-level install or --all for every detected agent.

Manual locations:

Claude Code:  ~/.claude/skills/unlazy
Codex CLI:    ~/.codex/skills/unlazy

Clone the repository into the relevant directory. Invoke it as /unlazy where slash skills are supported, $unlazy in Codex, or by a natural-language trigger from the skill description.

The core is SKILL.md. The checker and optional hook require Node 16 or newer and use no third-party runtime packages.

Quick start

Ask for substantial work with an explicit trigger:

/unlazy tree 5 refactor the payment module and verify every migration path

For a solo task, copy templates/gates-leaf.md to GATES.md, replace every placeholder, and inspect it without executing commands:

node <path-to-skill>/scripts/gate-check.mjs --status GATES.md

--status is the only mode that is always non-executing. On a new oracle with no exact approval record, a normal run prints its resolved command, expectation, working directory, shell, and PATH without executing it:

node <path-to-skill>/scripts/gate-check.mjs GATES.md

Do not treat normal mode as a permanent dry run: once the exact oracle is approved, normal mode can execute it.

CHECK: lines are shell code. After reading every command and called script, approve and run the ledger:

node <path-to-skill>/scripts/gate-check.mjs --approve GATES.md

Re-run all runnable gates, including gates already marked complete:

node <path-to-skill>/scripts/gate-check.mjs --reverify GATES.md

Use --help for the complete current CLI.

The gate contract

# Gates: pricing behavior

- [ ] G1: pricing fixtures render the expected tiers
  CHECK: node scripts/verify-pricing.mjs
  EXPECT: pricing verification passed
  EVIDENCE: pending

- [ ] G2: checkout integration succeeds from its package
  CHECK: node scripts/verify-checkout.mjs
  EXPECT: checkout verification passed
  CWD: packages/checkout
  EVIDENCE: pending

A runnable gate passes only when its process exits 0 and EXPECT: matches combined output. Evidence records the resolved shell, resolved working directory, exit status, a short PATH fingerprint, and decisive output. The pre-execution transcript shows the resolved PATH, capped for display. Old evidence is not re-execution; parent verification uses --reverify.

The parser rejects zero-gate ledgers, duplicate ids, incomplete runnable gates, invalid expectations, and abandonment without a reason. It ignores fenced examples, preserves CRLF or LF when updating, and inserts a missing evidence line when needed.

The checker can prove only the command oracle you declare. It cannot infer that an English title and arbitrary shell code mean the same thing. Good gates therefore:

• read the artifact or service named by the outcome

• print a success-only marker after all assertions pass

• test an absence check against a known positive control

• measure supplied figures instead of copying them into EXPECT:

• review consequential manual outcomes with evidence proportional to risk

Full specification: references/gates.md.

Shell and PATH

The checker uses --shell first, then UNLAZY_SHELL, then Node's platform default shell. That default is /bin/sh on Unix and process.env.ComSpec on Windows with the platform fallback. Checks inherit the launch environment, including PATH.

This matters on Windows: a checker launched from Git Bash can see Unix-like tools that the same checker launched from PowerShell does not. --shell changes the interpreter; it does not install grep, tail, tr, or other external programs. Portable examples call repository-owned Node scripts.

Parent re-verification should use the same declared shell and required toolchain. A shell or PATH mismatch is a failed verification to resolve, not successful evidence.

Security boundary

Approval records live under ~/.unlazy/approved by default. UNLAZY_APPROVAL_DIR may select another real directory, but it must remain outside the checked repository. Each record is specific to the absolute ledger and gate, exact CHECK: and EXPECT:, resolved CWD: and shell, timeout, output and regex limits, platform, and full inherited PATH. Editing any bound input requires approval again.

Approval is consent, not a sandbox. Checks run with ambient filesystem, environment, credential, and network access. Scopes and ownership leases coordinate cooperating processes but do not restrict what a process can read or write. Review SECURITY.md before running inherited gates or installing the Stop hook.

Orchestration and parallel work

For work that needs fresh contexts, create one scoped pipeline under .unlazy/<scope>/:

.unlazy/<scope>/PLAN.md
.unlazy/<scope>/GATES.md
.unlazy/<scope>/gates/leaf-*.md
.unlazy/<scope>/gates/node-*.md

The driver fixes interfaces, dependencies, conventions, and file ownership before dispatch. Leaves use declared WAITING, READY, IN-FLIGHT, VERIFIED, or ABANDONED states. Branches use OPEN, VERIFIED, or ABANDONED.

Ready leaves may run together only after each declares complete, disjoint, repository-relative OWNS: paths and claims them:

node <path-to-skill>/scripts/gate-check.mjs --scope api --leaf leaf-1.2.1 --claim

Lease matching is conservative and may reject a safe-looking pair. It is a coordination guard, not write isolation. Use separate worktrees for colliding worktree-local output, and configure separate cache locations when cache writes can conflict.

Dispatch is rolling: when a verified leaf unblocks another, start the newly ready leaf without waiting for unrelated work. Gate checks remain sequential by default. --jobs <N>, where N is an integer from 1 through 64, is an opt-in rolling limit for independent checks and keeps reporting in ledger order.

Read references/method.md, references/orchestration.md, and references/parallel.md before parallel fan-out.

Optional Claude Code Stop hook

The hook scans the current session's resolved ledger and returns Claude Code's documented top-level decision: "block" response while gates remain unmet. It does not execute checks. Its own session-keyed progress guard releases after six consecutive blocks without ledger progress.

Install only with the user's consent:

node <path-to-skill>/scripts/install-hooks.mjs
node <path-to-skill>/scripts/install-hooks.mjs --scope api
node <path-to-skill>/scripts/install-hooks.mjs --uninstall

Default installation writes .claude/settings.local.json. Keep that file, .unlazy/, and .unlazy-hook-state.json in the project's ignore rules. --shared writes absolute Node and hook-script paths into project settings, so it is usually not portable and can expose local directory names. --global writes the current user's Claude settings.

The installer preserves unrelated hooks, refuses malformed settings shapes, and identifies moved unlazy entries without depending on the install directory name. It writes settings atomically and creates <settings-file>.unlazy.bak beside an existing settings file before replacing it.

What 2.1.0 changes

The unreleased 2.1.0 source integrates the useful parts of community PRs while repairing their edge cases:

• strict shared ledger parsing and explicit named-file targeting

• --reverify, explicit --approve, and fail-closed exit-plus-EXPECT success

• --shell and UNLAZY_SHELL, with pre-execution PATH disclosure and resolved shell, CWD, exit, and output evidence

• scoped pipelines, session routing, atomic ledger updates, and serialized lease coordination

• rolling orchestration and opt-in --jobs, sequential by default

• session-keyed Stop-hook state and atomic settings updates with a backup

• Node 16 support, zero runtime dependencies, a package test command, and CI

• accurate security, portability, research, and reproducibility documentation

Contributor history and pull-request links are recorded in CHANGELOG.md.

Repository map

SKILL.md                         core instructions and mode routing
SECURITY.md                      CHECK, shell, approval, hook, and lease threat model
agents/openai.yaml               skill UI metadata
references/gates.md              strict format, approval, shell, and authoring rules
references/method.md             Depth Tree decomposition method
references/orchestration.md      states, rolling dispatch, and verification hierarchy
references/parallel.md           scope and lease coordination limits
references/token-economy.md      attention and verification cost discipline
research/validation-protocol.md  historical limitations and rerun protocol
templates/                       plan, leaf, and branch ledger templates
scripts/                         checker, shared parser, installer, and Stop hook
tests/                           deterministic behavior and regression tests

Run the repository's complete test command:

npm test