@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: 2.0.0. npm availability and dist-tags are separate release evidence; inspect the registry rather than inferring publication from source metadata.

See the 2.0.0 release notes, the 1.5.2 exact Lex alignment release, the 1.5.1 release correction, 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.