@smartergpt/lexrunner

LexRunner (lexrunner)

LexRunner turns a changing set of pull requests into a reviewable integration program: discover the work, freeze a dependency plan, run bounded gates, preserve evidence, and merge only with explicit authority.

It is useful when a repository has concurrent PRs, dependencies between changes, repeated local and CI checks, or agent-assisted implementation that needs a durable handoff. It is usually not a fit for a repository with one occasional PR and no integration-order problem.

Ask your agent: “Read docs/agent-evaluation.md, evaluate this repository without installing or changing anything, and return adopt, pilot, defer, or not a fit with the smallest reversible trial.”

That evaluation is deliberately read-only. Installing the package, writing a plan, creating a branch, pushing, opening a PR, or merging requires separate approval.

What works today

LexRunner’s supported workflow has grown in layers. A normal user can stop at any layer.

Layer	Current capability	First surface
Deterministic plan	Freeze PRs and declared dependencies into schema-versioned plan.json	lexrunner weave plan
Merge-weave	Compute merge order, preview integration, run gates, and apply authorized merges	lexrunner weave *, lexrunner gate run
Run and evidence	Persist bounded receipts, independent verification, acceptance, and artifacts	lexrunner attempt *
Fanout	Harvest and analyze issue/PR evidence for parallel work planning	lexrunner fanout *
Assisted agent work	Prepare an immutable packet and workspace envelope, attach a foreground-owned worker, then verify its claims	CLI/MCP Attempt lifecycle

The ADR-010 coordination model is accepted and its assisted Attempt lifecycle is implemented. LexRunner also has a tested headless reconciliation application boundary, but it is not a general production supervisor: there is no approved public headless launch surface, native host/reboot recovery remains release evidence, and Stage 5 fault-injection and authority expansion remain unproven. See ADR-010 and the headless proof boundary.

Smallest useful trial

First inspect without mutation:

lexrunner --version
lexrunner workspace doctor --json
lexrunner weave discover --json

After approving a local, reversible artifact, freeze and inspect a plan:

lexrunner weave plan --from-github --output plan.json --json
lexrunner schema validate plan.json --json
lexrunner weave merge-order plan.json --json
lexrunner gate run plan.json --dry-run --json

These commands do not merge. lexrunner weave apply --execute is a separate mutation and should be run only after reviewing the frozen plan, authority, gates, and target branch.

For a guided merge-weave walkthrough, use MERGE_WEAVE_QUICKSTART.md.

Architecture boundary

LexRunner has two contracts that must not be blurred:

• Stateless integration core: plan, gate, status, and weave services consume frozen inputs. At integration time, plan.json is the sole authority for dependency order and merge intent. The integration core never reads coordination state or .smartergpt/ as hidden truth.
• Explicitly stateful coordination service: ADR-010 WorkItems, Runs, Attempts, controller leases, workspace leases, receipts, and verification live behind CoordinationStore and workspace lifecycle adapters. That state coordinates implementation work; it does not authorize the integration core or silently alter a frozen plan.

.smartergpt/ is a portable example profile, not a runtime dependency. User/work artifacts belong in explicit stores, ignored local deliverables, CI artifacts, or PR comments—not in the package source tree. Canonical terms live in docs/TERMS.md.

Authority and safety

• Discovery, status, planning, schema validation, merge-order calculation, and dry runs are non-merging operations.
• Gate commands execute the commands declared by the reviewed plan; inspect them before running.
• Git/GitHub writes, delivery, release, and merge are separate authority lanes.
• Worker receipts are claims. LexRunner-owned verification and acceptance are the evidence used by the coordinator.
• Assisted and headless control share durable nouns and fencing rules; neither mode gains implicit merge, credential, release, or external-service authority.

Install and authenticate

Ecosystem 3.1 requires Node.js 24 or newer. The package is restricted under the SmarterGPT npm organization, so a human with organization access must authenticate the npm CLI once:

npm login --scope=@smartergpt --registry=https://registry.npmjs.org/
npm install --save-dev @smartergpt/lexrunner
npx lexrunner --version

Global installation is also supported:

npm install --global @smartergpt/lexrunner
lexrunner --version

Do not place npm tokens in the repository or a chat transcript. Windows/private-package validation is documented in the Node 24 migration guide.

lexrunner is the canonical CLI name. The existing lex-pr executable remains an additive compatibility alias and invokes the same program, so existing automation does not need to change.

The checked-in package version is the single source for lexrunner --version and lex-pr --version.

Current repository package version: 1.5.1. npm availability and dist-tags are separate release evidence; inspect the registry rather than inferring publication from source metadata.

See the 1.5.1 release notes, the 1.4.1 canonical CLI release, the 1.4.0 native-host boundary release, the 1.3.0 dogfood release, the 1.2.1 publication repair, and the underlying 1.2.0 compatibility decision for package disposition, semver rationale, supported assisted behavior, and deferred guarantees.

Choose a surface

• Human CLI: start with workspace doctor, weave discover, weave plan, weave merge-order, and gate run.
• Agent/MCP: use the matching canonical tools and bounded contracts in docs/AX.md and README.mcp.md.
• Assisted agent work: run attempt preflight before packet construction. When it reports broker_required, use attempt projection status|prepare to bind the exact committed base into native WSL, then continue with attempt prepare, attempt start, worker attachment/heartbeat, receipt submission, verification, and acceptance. The foreground host still owns worker launch. Follow the native Windows-to-WSL projection workflow for recovery and cleanup.
• Advanced operators: read the orchestration primitives, headless supervisor boundary, and security guidance.

The normative CLI/MCP inventory is generated from live registrations and stored in docs/architecture/cli-mcp-surface.json. Deprecated top-level aliases remain migration aids, not recommended entry points.

Reading order

• Agent fit evaluation — decide whether to adopt, pilot, defer, or decline.
• Merge-weave quickstart — run the smallest integration workflow.
• Canonical CLI/MCP surface — choose stable commands and tools.
• AX contract — understand bounded output, errors, parity, and exceptions.
• ADR-010 — understand assisted agent-work ownership and maturity.
• Documentation index — browse operator, fanout, MCP, audit, security, and contributor material.

Historical v2 design drafts are retained for provenance only. They do not describe a sibling package, active migration, or current runtime contract.

Development

nvm use
npm ci
npm run lint
npm run build

For implementation work, use the touched/adjacent gate selector and let CI prove the full suite on high-risk changes:

lexrunner gate select --base <base-sha> --head <head-sha> --json

Release validation remains exhaustive. See AGENTS.md, CONTRIBUTING.md, and the implementation gate contract.

Package and licensing

• Package: @smartergpt/lexrunner
• CLI: lexrunner (lex-pr compatibility alias)
• MCP bin: lexrunner-mcp
• Runtime dependency: @smartergpt/lex (MIT)
• LexRunner license: SmarterGPT Source-Available Personal Use License

See LICENSE.md, NOTICE.md, and ADR-008.