@smartergpt/lexrunner 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-09-09
+
+### Added
+
+- Progressive root CLI help shows seven existing work, integration and setup families.
+  `--help-all` exposes every registered command family and compatibility alias;
+  nested help and typo suggestions retain the complete command inventory.
+
+### Fixed
+
+- First-use help saves the actual integration plan with `--output plan.json` instead
+  of redirecting the planner summary. Guidance distinguishes reads, writes, gate
+  execution, worker handoff and separate merge authority.
+
+### Documentation
+
+- Explain the selected-work assisted handoff through preparation, attachment,
+  observed effects, receipts and verification. Controlled composition tests do not
+  establish a real worker provider or native Windows preparation support.
+- Repository exploration and compact-resumption scripts remain opt-in development
+  tools, outside the npm package. No token, cost or efficacy improvement is claimed.
+
 ## [2.3.0] - 2026-09-09
 
 ### Added

package/README.md

@@ -17,13 +17,19 @@ branch, pushing, opening a PR, or merging requires separate approval.
 
 ## Start here
 
+The [2.4.0 candidate](docs/releases/2.4.0.md) (pending release) makes `lexrunner --help` show the main work and integration families with a first-use
+path. Use `lexrunner --help-all` for every family and compatibility alias, or
+`lexrunner <command> --help` for full options and nested operations. Help changes
+presentation only; command effects and authority requirements still apply.
+The public 2.3.0 package does not yet contain this help view or `--help-all`.
+
 For your first trial, install **LexRunner only** in a GitHub repository with open
 PRs. Node.js 24+ and Git are required. npm installs LexRunner's dependencies; you
 do not need to install Lex, AXF, LexSona, a policy-host service, or an MCP server
-separately for this CLI workflow. These examples use the published 2.2.0 release.
+separately for this CLI workflow. These examples use the published 2.3.0 release.
 
 ```bash
-npm install --save-dev @smartergpt/lexrunner@2.2.0
+npm install --save-dev @smartergpt/lexrunner@2.3.0
 npx lexrunner --version
 npx lexrunner weave discover --json
 ```
@@ -118,11 +124,11 @@ The checked-in package version is the single source for `lexrunner --version` an
 
 <!-- BEGIN GENERATED PACKAGE VERSION -->
 
-Current repository package version: **2.3.0**. npm availability and dist-tags are separate
+Current repository package version: **2.4.0**. npm availability and dist-tags are separate
 release evidence; inspect the registry rather than inferring publication from source metadata.
 <!-- END GENERATED PACKAGE VERSION -->
 
-See the [2.3.0 selected-work candidate](docs/releases/2.3.0.md), the
+See the [2.3.0 selected-work release](docs/releases/2.3.0.md), the
 [2.2.0 frozen-input release](docs/releases/2.2.0.md), the
 [2.1.0 open-source release](docs/releases/2.1.0.md), the
 [2.0.2 generated timeout correction](docs/releases/2.0.2.md), the

package/dist/cli.cjs

@@ -26871,7 +26871,7 @@ var import_config3 = require("dotenv/config");
 // package.json
 var package_default = {
   name: "@smartergpt/lexrunner",
-  version: "2.3.0",
+  version: "2.4.0",
   type: "module",
   engines: {
     node: ">=24"
@@ -27050,7 +27050,7 @@ var package_default = {
 };
 
 // src/cli.ts
-var import_commander6 = require("commander");
+var import_commander7 = require("commander");
 var import_node_url7 = require("url");
 var import_node_path41 = require("path");
 var import_chalk14 = __toESM(require("chalk"), 1);
@@ -70252,6 +70252,67 @@ function emitAliasWarning(command, write = (message) => process.stderr.write(mes
 `);
 }
 
+// src/cli/progressive-help.ts
+var import_commander6 = require("commander");
+var FIRST_USE_COMMANDS = /* @__PURE__ */ new Set([
+  "idea",
+  "create-project",
+  "attempt",
+  "weave",
+  "gate",
+  "schema",
+  "workspace",
+  "help"
+]);
+function configureProgressiveHelp(root) {
+  root.configureHelp({
+    formatHelp(command, helper) {
+      if (command !== root || root.opts().helpAll) {
+        return import_commander6.Help.prototype.formatHelp.call(this, command, helper);
+      }
+      const presentation = Object.create(helper);
+      presentation.visibleCommands = (entry) => {
+        const commands = helper.visibleCommands(entry);
+        return entry === root ? commands.filter((child) => FIRST_USE_COMMANDS.has(child.name())) : commands;
+      };
+      return import_commander6.Help.prototype.formatHelp.call(this, command, presentation);
+    }
+  });
+  root.option("--help-all", "Show all command families and compatibility aliases").on("option:help-all", () => root.help());
+  root.addHelpText(
+    "after",
+    `
+Start with a reviewable GitHub integration plan:
+  lexrunner weave discover --json                          Read open PRs from GitHub
+  lexrunner weave plan --from-github --output plan.json --json
+                                                          Read GitHub and write the plan file
+  lexrunner schema validate plan.json --json               Validate the saved plan
+  lexrunner weave merge-order plan.json --json              Inspect dependency order
+  lexrunner gate run plan.json --dry-run --json              Preview gates without running them
+
+Choose an unused plan filename. Inspect selected heads, dependencies and executable
+gate commands. Preview may write local diagnostics; it proves neither passed gates
+nor review or merge authority. Later gate execution runs commands; weave apply
+--execute changes Git state and requires separate review and explicit authority.
+
+Plan and carry out authored work:
+  lexrunner idea --help             Capture an idea; normal execution may create GitHub issues
+  lexrunner create-project --help   Build a work plan; may write files and create issues
+  lexrunner attempt --help          Materialize selected work, prepare, attach, submit and verify
+Selection and materialization do not launch workers. Preparation changes workspace
+and lifecycle state; the assisted host owns actual worker launch and dispatch.
+Completion requires evidence and reassessment against success criteria.
+
+Explore further:
+  lexrunner --help-all              All command families, aliases, diagnostics and recovery
+  lexrunner <command> --help        Full help for that command, including nested operations
+  lexrunner workspace --help        Setup and environment diagnostics
+
+Walkthrough: https://github.com/SmarterGPT/lexrunner/blob/main/MERGE_WEAVE_QUICKSTART.md
+`
+  );
+}
+
 // src/commands/explain.ts
 var import_promises20 = __toESM(require("fs/promises"), 1);
 var import_path10 = __toESM(require("path"), 1);
@@ -77822,7 +77883,7 @@ ${prefix} Unexpected error: ${String(err?.message ?? e)}
   }
   throwExit(1);
 }
-var program = new import_commander6.Command();
+var program = new import_commander7.Command();
 program.exitOverride((err) => {
   throw new CLIExitSignal(err.exitCode ?? 1, err.message);
 });
@@ -77850,63 +77911,8 @@ program.name("lexrunner").description(
     setFrameEmissionEnabled(globalFlags.emitFrames);
   }
   emitAliasWarning(actionCommand);
-}).addHelpText(
-  "after",
-  `
-Examples (Canonical Category-Action Pattern):
-	$ lexrunner workspace init                 Initialize workspace with interactive setup
-	$ lexrunner workspace doctor               Validate environment and configuration
-	$ lexrunner idea                           Capture feature idea interactively
-	$ lexrunner idea --title "..." --description "..." --dry-run
-	$ lexrunner config show                    Display configuration with precedence chain
-	$ lexrunner config show --key scope.target Show specific configuration value
-	$ lexrunner config show --json             Output configuration in JSON format
-	$ lexrunner config:inspect                 Display merged configuration with provenance map
-	$ lexrunner weave discover                 Find open PRs matching scope
-	$ lexrunner weave discover --suggest       Generate dependency suggestions with heuristics
-	$ lexrunner weave plan --from-github       Generate merge plan from GitHub PRs
-	$ lexrunner plan-review plan.json          Interactively review and edit plan
-	$ lexrunner plan-diff plan1.json plan2.json  Compare two plans
-	$ lexrunner gate run plan.json             Run quality gates on plan
-	$ lexrunner orchestrate:analyze-issues     Analyze issues for parallel work planning (fanout commands coming soon)
-	$ lexrunner orchestrate:analyze-issues --labels priority:P1 --json
-	$ lexrunner security check-rotation        Check token rotation status
-	$ lexrunner security scan-plan             Scan a plan file for secrets
-	$ lexrunner security validate-secrets GITHUB_TOKEN OTHER_SECRET
-
-Governance (LexSona Shadow Mode):
-	$ lexrunner governance:report              Analyze shadow governance logs
-	$ lexrunner governance:report --format markdown --disagreements-only
-	$ lexrunner governance:report --since 2025-12-01 --persona quality-first_engineering
-	$ lexrunner governance:cleanup             Clean up old governance logs
-
-Power User Commands:
-	$ lexrunner view plan.json                 Interactive plan viewer
-	$ lexrunner query plan.json --stats        Plan statistics and analysis
-	$ lexrunner query plan.json "level eq 1"   Query items by criteria
-	$ lexrunner retry --filter failed          Retry failed gates
-	$ lexrunner completion bash                Generate bash completion script
-
-Canonical Workflow:
-	1. Ideate:      lexrunner idea (capture feature ideas as GitHub Issues)
-	2. Discover:    lexrunner weave discover (optionally add --suggest for dependencies)
-	3. Plan:        lexrunner weave plan --from-github --json > plan.json
-	4. Review:      lexrunner plan-review plan.json
-	5. Execute:     lexrunner gate run plan.json
-	6. Report:      lexrunner weave report artifacts --out md
-
-Legacy Commands (Deprecated, use canonical forms above):
-	$ lexrunner init       \u2192 lexrunner workspace init
-	$ lexrunner doctor     \u2192 lexrunner workspace doctor
-	$ lexrunner discover   \u2192 lexrunner weave discover
-	$ lexrunner plan       \u2192 lexrunner weave plan
-	$ lexrunner status     \u2192 lexrunner weave status
-	$ lexrunner report     \u2192 lexrunner weave report
-	$ lexrunner execute    \u2192 lexrunner gate run
-	$ lexrunner orchestrate:analyze-issues \u2192 lexrunner fanout analyze
-	$ lexrunner orchestrate:assign-batch   \u2192 lexrunner fanout assign
-`
-);
+});
+configureProgressiveHelp(program);
 registerGateReportCommand(program);
 registerGovernanceReportCommand(program);
 registerGovernanceCleanupCommand(program);
@@ -78534,7 +78540,7 @@ async function main(argv = process.argv) {
       }
       return;
     }
-    if (error instanceof import_commander6.CommanderError) {
+    if (error instanceof import_commander7.CommanderError) {
       const exitCode = typeof error.exitCode === "number" ? error.exitCode : 1;
       process.exitCode = exitCode;
       if (exitCode !== 0 && error.message) {

package/dist/cli.js

@@ -476,7 +476,7 @@ import "dotenv/config";
 // package.json
 var package_default = {
   name: "@smartergpt/lexrunner",
-  version: "2.3.0",
+  version: "2.4.0",
   type: "module",
   engines: {
     node: ">=24"
@@ -655,7 +655,7 @@ var package_default = {
 };
 
 // src/cli.ts
-import { Command as Command6, CommanderError } from "commander";
+import { Command as Command7, CommanderError } from "commander";
 import { fileURLToPath as fileURLToPath6 } from "url";
 import { resolve as resolve15 } from "path";
 import chalk11 from "chalk";
@@ -43626,6 +43626,67 @@ function emitAliasWarning(command, write = (message) => process.stderr.write(mes
 `);
 }
 
+// src/cli/progressive-help.ts
+import { Help } from "commander";
+var FIRST_USE_COMMANDS = /* @__PURE__ */ new Set([
+  "idea",
+  "create-project",
+  "attempt",
+  "weave",
+  "gate",
+  "schema",
+  "workspace",
+  "help"
+]);
+function configureProgressiveHelp(root) {
+  root.configureHelp({
+    formatHelp(command, helper) {
+      if (command !== root || root.opts().helpAll) {
+        return Help.prototype.formatHelp.call(this, command, helper);
+      }
+      const presentation = Object.create(helper);
+      presentation.visibleCommands = (entry) => {
+        const commands = helper.visibleCommands(entry);
+        return entry === root ? commands.filter((child) => FIRST_USE_COMMANDS.has(child.name())) : commands;
+      };
+      return Help.prototype.formatHelp.call(this, command, presentation);
+    }
+  });
+  root.option("--help-all", "Show all command families and compatibility aliases").on("option:help-all", () => root.help());
+  root.addHelpText(
+    "after",
+    `
+Start with a reviewable GitHub integration plan:
+  lexrunner weave discover --json                          Read open PRs from GitHub
+  lexrunner weave plan --from-github --output plan.json --json
+                                                          Read GitHub and write the plan file
+  lexrunner schema validate plan.json --json               Validate the saved plan
+  lexrunner weave merge-order plan.json --json              Inspect dependency order
+  lexrunner gate run plan.json --dry-run --json              Preview gates without running them
+
+Choose an unused plan filename. Inspect selected heads, dependencies and executable
+gate commands. Preview may write local diagnostics; it proves neither passed gates
+nor review or merge authority. Later gate execution runs commands; weave apply
+--execute changes Git state and requires separate review and explicit authority.
+
+Plan and carry out authored work:
+  lexrunner idea --help             Capture an idea; normal execution may create GitHub issues
+  lexrunner create-project --help   Build a work plan; may write files and create issues
+  lexrunner attempt --help          Materialize selected work, prepare, attach, submit and verify
+Selection and materialization do not launch workers. Preparation changes workspace
+and lifecycle state; the assisted host owns actual worker launch and dispatch.
+Completion requires evidence and reassessment against success criteria.
+
+Explore further:
+  lexrunner --help-all              All command families, aliases, diagnostics and recovery
+  lexrunner <command> --help        Full help for that command, including nested operations
+  lexrunner workspace --help        Setup and environment diagnostics
+
+Walkthrough: https://github.com/SmarterGPT/lexrunner/blob/main/MERGE_WEAVE_QUICKSTART.md
+`
+  );
+}
+
 // src/commands/explain.ts
 import fs46 from "fs/promises";
 import path53 from "path";
@@ -51144,7 +51205,7 @@ ${prefix} Unexpected error: ${String(err?.message ?? e)}
   }
   throwExit(1);
 }
-var program = new Command6();
+var program = new Command7();
 program.exitOverride((err) => {
   throw new CLIExitSignal(err.exitCode ?? 1, err.message);
 });
@@ -51172,63 +51233,8 @@ program.name("lexrunner").description(
     setFrameEmissionEnabled(globalFlags.emitFrames);
   }
   emitAliasWarning(actionCommand);
-}).addHelpText(
-  "after",
-  `
-Examples (Canonical Category-Action Pattern):
-	$ lexrunner workspace init                 Initialize workspace with interactive setup
-	$ lexrunner workspace doctor               Validate environment and configuration
-	$ lexrunner idea                           Capture feature idea interactively
-	$ lexrunner idea --title "..." --description "..." --dry-run
-	$ lexrunner config show                    Display configuration with precedence chain
-	$ lexrunner config show --key scope.target Show specific configuration value
-	$ lexrunner config show --json             Output configuration in JSON format
-	$ lexrunner config:inspect                 Display merged configuration with provenance map
-	$ lexrunner weave discover                 Find open PRs matching scope
-	$ lexrunner weave discover --suggest       Generate dependency suggestions with heuristics
-	$ lexrunner weave plan --from-github       Generate merge plan from GitHub PRs
-	$ lexrunner plan-review plan.json          Interactively review and edit plan
-	$ lexrunner plan-diff plan1.json plan2.json  Compare two plans
-	$ lexrunner gate run plan.json             Run quality gates on plan
-	$ lexrunner orchestrate:analyze-issues     Analyze issues for parallel work planning (fanout commands coming soon)
-	$ lexrunner orchestrate:analyze-issues --labels priority:P1 --json
-	$ lexrunner security check-rotation        Check token rotation status
-	$ lexrunner security scan-plan             Scan a plan file for secrets
-	$ lexrunner security validate-secrets GITHUB_TOKEN OTHER_SECRET
-
-Governance (LexSona Shadow Mode):
-	$ lexrunner governance:report              Analyze shadow governance logs
-	$ lexrunner governance:report --format markdown --disagreements-only
-	$ lexrunner governance:report --since 2025-12-01 --persona quality-first_engineering
-	$ lexrunner governance:cleanup             Clean up old governance logs
-
-Power User Commands:
-	$ lexrunner view plan.json                 Interactive plan viewer
-	$ lexrunner query plan.json --stats        Plan statistics and analysis
-	$ lexrunner query plan.json "level eq 1"   Query items by criteria
-	$ lexrunner retry --filter failed          Retry failed gates
-	$ lexrunner completion bash                Generate bash completion script
-
-Canonical Workflow:
-	1. Ideate:      lexrunner idea (capture feature ideas as GitHub Issues)
-	2. Discover:    lexrunner weave discover (optionally add --suggest for dependencies)
-	3. Plan:        lexrunner weave plan --from-github --json > plan.json
-	4. Review:      lexrunner plan-review plan.json
-	5. Execute:     lexrunner gate run plan.json
-	6. Report:      lexrunner weave report artifacts --out md
-
-Legacy Commands (Deprecated, use canonical forms above):
-	$ lexrunner init       \u2192 lexrunner workspace init
-	$ lexrunner doctor     \u2192 lexrunner workspace doctor
-	$ lexrunner discover   \u2192 lexrunner weave discover
-	$ lexrunner plan       \u2192 lexrunner weave plan
-	$ lexrunner status     \u2192 lexrunner weave status
-	$ lexrunner report     \u2192 lexrunner weave report
-	$ lexrunner execute    \u2192 lexrunner gate run
-	$ lexrunner orchestrate:analyze-issues \u2192 lexrunner fanout analyze
-	$ lexrunner orchestrate:assign-batch   \u2192 lexrunner fanout assign
-`
-);
+});
+configureProgressiveHelp(program);
 registerGateReportCommand(program);
 registerGovernanceReportCommand(program);
 registerGovernanceCleanupCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartergpt/lexrunner",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "engines": {
     "node": ">=24"