@smartergpt/lexrunner 1.0.0 → 1.3.0

package/CHANGELOG.md

@@ -6,7 +6,115 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## [Unreleased]
 
-_No unreleased changes._
+## [1.3.0] - 2026-07-30
+
+### Added
+
+- **Windows-to-native-WSL Attempt projection** - Added a read-only containment preflight,
+  versioned projection and path-mapping contracts, rollback-safe native provisioning, and
+  identity-bound launch, worker, receipt, verification, acceptance, and cleanup behavior.
+- **Shared projection lifecycle** - Added matching CLI
+  `attempt projection prepare|status|cleanup|quarantine` operations and MCP lifecycle tools with
+  explicit mutation authority, path-private diagnostics, bounded quarantine inspection, and a
+  recovery runbook.
+- **Independent merge review gate** - Documented a mandatory-by-default, exact-head review step
+  whose verdict is invalidated by candidate changes and whose opt-out requires an explicit warned
+  `review_bypassed` receipt.
+
+### Fixed
+
+- **Plan validation diagnostics** - Return the individual validation failures instead of only an
+  aggregate count, preserving the dogfood evidence needed to repair invalid plans.
+- **Explicit plan references** - Resolve explicitly selected plan artifacts consistently across
+  MCP status, ordering, and gate operations.
+- **Projection durability and recovery** - Fail closed across selection revocation/publication,
+  staging ownership, quarantine marker persistence, directory sync failures, source refresh, and
+  active-worktree cleanup refusal.
+
+---
+
+## [1.2.1] - 2026-07-21
+
+### Fixed
+
+- **npm executable metadata** - Removed the leading `./` from the `lexrunner-mcp` bin target and
+  normalized the repository URL so npm preserves both CLI executables without publish-time repair.
+- **Human publication gate** - Added a package-boundary validation for npm-normalized metadata and
+  a dry-run release gate that prints, but never executes, the final authenticated publish command.
+- **Canonical release tags** - Reconciled the release workflow, preparation and drift scripts,
+  publication gate, and operator guidance on the required `lexrunner-v*` tag prefix.
+
+### Release note
+
+- `v1.2.0` remains an immutable GitHub release but was not published to npm after the dry run exposed
+  the removable MCP bin metadata. Use `1.2.1` for the private npm release and downstream proof.
+
+---
+
+## [1.2.0] - 2026-07-21
+
+### Added
+
+- **Assisted agent-work lifecycle** - Added ADR-010 WorkItem, Run, Attempt, packet, envelope,
+  workspace, WorkerSession, receipt, engine-verification, acceptance, retry-delta, and fan-in
+  contracts with fenced memory and SQLite persistence.
+- **Public lifecycle surfaces** - Added bounded CLI and MCP adapters for Attempt preparation,
+  start/status, worker attachment and heartbeat, receipt submission, independent verification,
+  and policy acceptance.
+- **Recovery and containment** - Added native worktree brokering, physical directory identity,
+  incomplete-launch reconciliation, runtime authority negotiation/enforcement, fail-forward
+  supervisor services, and persisted merge-weave resume.
+- **Shared integration services** - Added canonical shared services for gate execution, discovery,
+  planning, status, merge order/application, workspace configuration, and bounded IntegrationRun
+  compatibility.
+- **Release evidence** - Added generated CLI/MCP documentation, touched/adjacent implementation
+  gate selection, deterministic package-boundary validation, clean packed-package smoke, and
+  ecosystem dogfood isolation.
+
+### Changed
+
+- **Documentation and ADR-010 reconciliation** - Reframed LexRunner around its progressive
+  integration workflow, distinguished the stateless integration core from optional stateful
+  coordination, documented assisted-versus-headless maturity honestly, added a bounded read-only
+  agent evaluation, generated CLI/MCP surface and package-version facts from repository authority,
+  and corrected private npm publishing guidance for `@smartergpt/lexrunner`.
+- **Node.js 24 runtime floor** - Ecosystem 3.1 requires Node.js 24 or newer for the CLI,
+  MCP server, SDK package, and downstream consumers. Node.js 20 is EOL and Node.js 22 is no
+  longer a supported LexRunner runtime. Upgrade local, CI, and Windows consumer environments
+  before installing this release. The package intentionally has no speculative upper bound;
+  Node 24 is the validated release line and later majors remain installable for forward testing.
+- **Lex 3 compatibility** - Updated the runtime dependency from `@smartergpt/lex@^2.10.0` to
+  `@smartergpt/lex@^3.0.1` after validating that every LexRunner-imported export remains present
+  and the Node 24 build, integration tests, and packed consumer succeed.
+
+### Fixed
+
+- **Published package boundary** - Replaced broken `.smartergpt` schema export targets with built
+  ESM/CommonJS/declaration artifacts, bounded the tarball allowlist, and verified the real packed
+  CLI and MCP bins.
+- **Canonical surface drift** - Centralized CLI alias warnings/removal windows and verified all
+  125 CLI registrations and 28 MCP tools against explicit dispositions and application-service
+  ownership.
+
+### Compatibility
+
+- No canonical CLI command, MCP tool, or package export key from 1.1 is removed. Deprecated aliases
+  remain migration-only and retain their declared 2.0 removal window.
+- The Node 24 floor is an intentional minor-release migration for Ecosystem 3.1. Node 20 and 22
+  consumers must upgrade before installing LexRunner 1.2.0.
+- Assisted orchestration is supported. A general public headless launcher, native reboot recovery,
+  and the complete Stage 5 hostile fault-injection/authority-expansion matrix remain deferred.
+
+---
+
+## [1.1.0] - 2026-02-08
+
+### Fixed
+
+- **SQLite package alignment** - Replaced `better-sqlite3` with `better-sqlite3-multiple-ciphers` ^12.6.2 (#730)
+  - LexRunner can now open encrypted Lex databases (cipher support via `pragma key`)
+  - Aligns all ecosystem repos (lex, lexsona, lexrunner) on the same SQLite package
+  - Drop-in replacement — no API changes, same `@types/better-sqlite3` types
 
 ---
 

package/LICENSE.md

@@ -0,0 +1,110 @@
+SmarterGPT Source-Available Personal Use License
+
+Version 1.0
+
+Copyright (c) Joseph Gustavson / Guffawaffle / SmarterGPT. All rights reserved.
+
+## 1. Purpose
+
+This project is publicly visible for review, learning, experimentation, personal use, and provenance.
+
+This project is source-available, not open source.
+
+Unless a separate written agreement says otherwise, this license does not grant commercial, organizational, employer, client, production, hosted-service, redistribution, sublicensing, or embedding rights.
+
+## 2. Definitions
+
+"Software" means the source code, documentation, schemas, examples, tests, configuration files, package materials, adapters, scripts, diagrams, and related materials in this repository.
+
+"Maintainer" means Joseph Gustavson / Guffawaffle / SmarterGPT.
+
+"Personal Use" means use by an individual person for private learning, experimentation, evaluation, research, non-commercial development, or personal projects not performed for an employer, client, company, organization, institution, or commercial purpose.
+
+"Organizational Use" means use by or for a company, employer, client, nonprofit, government agency, school, institution, team, contractor, vendor, or other organization.
+
+"Commercial Use" means use intended to generate revenue, reduce business costs, support paid work, support a product or service, support consulting or client work, support internal business operations, or otherwise provide business or professional advantage.
+
+## 3. Personal Use Grant
+
+Maintainer grants you a non-exclusive, worldwide, royalty-free license to view, copy, fork, modify, and run the Software for Personal Use only.
+
+You may create personal modifications and private experiments.
+
+You may not use the Software for Organizational Use or Commercial Use without a separate written license from Maintainer.
+
+## 4. Prohibited Uses Without Separate Written Permission
+
+Without a separate written license from Maintainer, you may not:
+
+1. use the Software for Organizational Use;
+2. use the Software for Commercial Use;
+3. use the Software in production systems;
+4. use the Software for employer, client, contractor, or consulting work;
+5. sell, resell, sublicense, redistribute, repackage, or commercialize the Software;
+6. provide the Software as a hosted service, managed service, SaaS feature, API, SDK, platform feature, or embedded component;
+7. incorporate the Software into a commercial or organizational product, service, workflow, platform, agent system, orchestration system, developer tool, or internal business system;
+8. remove copyright, license, attribution, provenance, or source-available notices;
+9. use the Software to access, process, store, transmit, or manage regulated data, customer data, medical data, PHI, secrets, credentials, production systems, or third-party confidential information;
+10. use the Software in a way that implies endorsement by Maintainer.
+
+## 5. Separate Commercial or Organizational Licenses
+
+Maintainer may grant separate written licenses for commercial, organizational, internal business, production, hosted, redistribution, sublicensing, or embedding use.
+
+A separate written agreement may grant rights broader than this public license.
+
+If a separate written agreement conflicts with this public license, the separate written agreement controls only for the party and scope covered by that agreement.
+
+Public availability of this repository does not grant any company, employer, client, or organization rights beyond those expressly stated in this license or a separate written agreement.
+
+## 6. Contributions
+
+Unless Maintainer has accepted a separate written contributor agreement, contributions submitted to this repository are offered under this same license.
+
+By submitting a pull request, patch, issue-attached code, documentation change, schema change, example, test, adapter, or other contribution, you represent that you have the right to submit it and that it does not contain confidential information, trade secrets, customer data, regulated data, PHI, credentials, or third-party proprietary material.
+
+By submitting a contribution, you grant Maintainer a perpetual, worldwide, royalty-free, irrevocable, non-exclusive license to use, reproduce, modify, distribute, sublicense, commercialize, and otherwise incorporate that contribution into this project and related SmarterGPT projects.
+
+Maintainer is not required to accept contributions.
+
+## 7. No Confidential or Regulated Data
+
+Do not submit confidential information, private source code, internal architecture, credentials, secrets, customer data, regulated data, PHI, medical data, security-sensitive information, or employer/client proprietary material to this repository.
+
+Maintainer may remove or reject any contribution that appears to contain such material.
+
+## 8. Third-Party Dependencies
+
+Third-party dependencies, libraries, tools, and assets remain subject to their own licenses.
+
+This license applies only to the Software owned or controlled by Maintainer.
+
+Nothing in this license grants rights to third-party materials beyond the rights provided by their respective licenses.
+
+## 9. Trademarks and Names
+
+This license does not grant rights to use the names, marks, logos, branding, project names, domain names, or identities of Maintainer, SmarterGPT, Guffawaffle, Lex, AXF, LexThority, LexRunner, LexSona, or related projects except as necessary for truthful attribution.
+
+## 10. No Patent License
+
+No patent license is granted by this license.
+
+## 11. No Warranty
+
+The Software is provided "as is," without warranties of any kind, express or implied, including warranties of merchantability, fitness for a particular purpose, title, non-infringement, security, accuracy, reliability, compliance, or uninterrupted operation.
+
+Use the Software at your own risk.
+
+## 12. Limitation of Liability
+
+To the maximum extent permitted by law, Maintainer will not be liable for any claim, damages, losses, costs, expenses, or liability arising from or related to the Software or this license, including direct, indirect, incidental, special, consequential, exemplary, or punitive damages.
+
+## 13. Reservation of Rights
+
+All rights not expressly granted by this license are reserved by Maintainer.
+
+This license does not transfer ownership of the Software or any copyright, trademark, patent, trade secret, or other intellectual property right.
+
+## 14. Contact
+
+For commercial, organizational, production, hosted, redistribution, sublicensing, embedding, or internal business use, contact Maintainer for a separate written license.

package/README.mcp.md

@@ -13,15 +13,16 @@ mcp_lexrunner_{category}_{action}
 ```
 
 **Categories:**
-| Category | Purpose |
-|----------|---------|
-| `plan` | Plan creation and validation |
-| `gate` | CI/gate execution |
-| `weave` | Merge-weave orchestration |
-| `workspace` | Local workspace management |
-| `run` | Run lifecycle management |
-| `executor` | Executor tools (Senior Dev, etc.) |
-| `core` | Cross-cutting utilities |
+
+| Category    | Purpose                           |
+| ----------- | --------------------------------- |
+| `plan`      | Plan creation and validation      |
+| `gate`      | CI/gate execution                 |
+| `weave`     | Merge-weave orchestration         |
+| `workspace` | Local workspace management        |
+| `run`       | Run lifecycle management          |
+| `executor`  | Executor tools (Senior Dev, etc.) |
+| `core`      | Cross-cutting utilities           |
 
 **Deprecated Aliases:** Old tool names (e.g., `plan.create`, `discover`) still work but are deprecated. Use canonical names for new integrations.
 
@@ -112,6 +113,40 @@ This MCP server follows the same architectural pattern as LexBrain and LexMap:
 
 ## Available Tools
 
+### preflight_attempt_containment
+
+Checks whether the current runtime and declared repository/worktree roots can host LexRunner's
+physical directory-identity boundary before an Attempt packet is constructed. This tool is always
+read-only and does not require `ALLOW_MUTATIONS`.
+
+It returns `native_ready`, `broker_required`, or `unsupported` with stable reason codes, bounded
+next actions, verification depth for each root, and a privacy-safe binding digest. Native Windows
+and WSL DrvFS/9P inputs recommend a native-WSL projection without weakening the containment
+boundary.
+
+### Native WSL projection lifecycle
+
+Four tools share one bounded lifecycle service with the matching
+`lex-pr attempt projection <operation> --input <file|-> --json` commands:
+
+- `get_native_wsl_projection_status` reads exact lifecycle state without creating control, lock,
+  projection, or SQLite state.
+- `inspect_native_wsl_projection_quarantine` reads privacy-bounded quarantine counts and entry
+  digests.
+- `prepare_native_wsl_projection` prepares or exactly reuses the requested committed base.
+- `cleanup_native_wsl_projection` removes an exact idle projection and its matching quarantine
+  state; active worktrees are refused.
+
+Prepare and cleanup require both `"mutation": {"authorized": true}` in the input and the MCP
+server mutation gate. Status and quarantine inspection remain available when mutations are
+disabled. All results omit source/native paths and expose stable digests, reason codes, bounded
+command evidence, counts, and next actions.
+
+On success, pass the returned `selectionDigest` to projected `attempt prepare`. Launch resolves
+the engine-authored selection, emits the machine-verifiable execution path mapping, and preserves
+the request's exact `base_sha` even when the Windows source HEAD or dirty state later changes.
+See the [native Windows-to-WSL projection workflow](docs/workflows/native-wsl-projection.md).
+
 ### mcp_lexrunner_plan_create
 
 Creates a plan from configuration files or auto-discovers from GitHub PRs. This is a **convenience wrapper** that combines PR discovery (`pr_list`), plan generation, validation, and file writing into a single operation.
@@ -427,11 +462,21 @@ Executes gates for plan items. Can work with either an internal plan (created vi
 
 > **Deprecated alias:** `gates.run`
 
+All overlapping integration tools use the same plan-reference precedence:
+
+1. `planFile`, when supplied. The explicit reference is authoritative and never falls through.
+2. `plan.json` in the repository root.
+3. `<profile>/runner/plan.json` as the backward-compatible `plan_create` fallback.
+
+Their results include the same path-independent `planArtifact` identity. Compare its canonical
+`digest` to verify that status, merge ordering, gate execution, and merge preview consumed the
+same frozen plan.
+
 **Parameters:**
 
-- `planFile` (string, optional): Path to external plan.json file. If not provided, uses internal state from the profile directory.
-- `onlyItem` (string, optional): Run gates for specific item only
-- `onlyGate` (string, optional): Run specific gate only
+- `planFile` (string, optional): Explicit path to an authored plan
+- `onlyItem` (string, optional): Execute gates for this item only
+- `onlyGate` (string, optional): Execute this gate only
 - `outDir` (string, optional): Output directory for gate results
 
 **Returns:**
@@ -450,11 +495,20 @@ Executes gates for plan items. Can work with either an internal plan (created vi
       ]
     }
   ],
-  "allGreen": true
+  "allGreen": true,
+  "planArtifact": {
+    "contract": "plan-artifact-identity-v1",
+    "kind": "execution-plan",
+    "schema": "lexrunner.execution-plan",
+    "schemaVersion": "1.0.0",
+    "digest": "sha256:...",
+    "target": "main",
+    "itemCount": 1
+  }
 }
 ```
 
-**Example (using internal plan):**
+**Example (using repository or profile fallback):**
 
 ```json
 {
@@ -480,7 +534,8 @@ Executes gates for plan items. Can work with either an internal plan (created vi
 
 **Use Cases:**
 
-- **Internal state**: Run gates on a plan created via `mcp_lexrunner_plan_create` (default behavior)
+- **Authored plan**: Run gates directly from a repository-root or explicitly referenced plan
+- **Profile fallback**: Continue using a plan created via `mcp_lexrunner_plan_create`
 - **External orchestration**: Run gates on programmatically-created or externally-managed plan files
 - **Parallel workflows**: Execute gates on multiple independent plans in parallel merge-weave operations
 
@@ -492,14 +547,29 @@ Applies merge operations with environment-based gating.
 
 **Parameters:**
 
+- `planFile` (string, optional): Explicit path to an authored plan, using the same fallback precedence as gate execution
 - `dryRun` (boolean, optional): Simulate merge without making changes (default: `true`)
 
 **Returns:**
 
 ```json
 {
-  "allowed": false,
-  "message": "Mutations not allowed. Set ALLOW_MUTATIONS=true or use dryRun=true."
+  "mode": "dry-run",
+  "dryRun": true,
+  "ok": true,
+  "status": "preview",
+  "totalItems": 1,
+  "levels": [["item1"]],
+  "artifactRefs": [],
+  "planArtifact": {
+    "contract": "plan-artifact-identity-v1",
+    "kind": "execution-plan",
+    "schema": "lexrunner.execution-plan",
+    "schemaVersion": "1.0.0",
+    "digest": "sha256:...",
+    "target": "main",
+    "itemCount": 1
+  }
 }
 ```
 
@@ -509,6 +579,7 @@ Applies merge operations with environment-based gating.
 {
   "name": "mcp_lexrunner_weave_apply",
   "arguments": {
+    "planFile": "plan.json",
     "dryRun": true
   }
 }
@@ -579,6 +650,7 @@ const externalGatesResult = await client.callTool("mcp_lexrunner_gate_run", {
 
 // Check merge eligibility (dry run)
 const mergeResult = await client.callTool("mcp_lexrunner_weave_apply", {
+  planFile: "/tmp/merge-batch/plan.json",
   dryRun: true,
 });
 ```