@smartergpt/lexrunner 1.0.0 → 1.2.1

package/docs/CLI_VERBS.md

@@ -1,219 +0,0 @@
-# CLI Verbs & Categories Contract
-
-**Canonical Structure:** `lex-pr <category> <action> [--flags...]`
-
-This document defines the stable vocabulary for lexrunner commands.
-
----
-
-## Core Principle
-
-Commands follow a **category-action** structure where:
-
-- **Category** = domain noun (what area of the system)
-- **Action** = shared verb (what operation to perform)
-
-This makes commands discoverable, consistent, and self-documenting.
-
----
-
-## Categories (Domain Nouns)
-
-| Category    | Purpose                                    | Lifecycle Phase    |
-| ----------- | ------------------------------------------ | ------------------ |
-| `fanout`    | Worker/issue distribution                  | Pre-implementation |
-| `weave`     | Integration pipeline (merge pyramid)       | Integration-time   |
-| `workspace` | `.smartergpt` profile/config lifecycle     | Setup/maintenance  |
-| `gate`      | Quality checks (lint, test, policy)        | Validation         |
-| `security`  | Security scanning and guardrails           | Safety             |
-| `safety`    | Safety framework (kill switches, rollback) | Safety             |
-| `audit`     | Audit logging and compliance               | Observability      |
-| `ax`        | AX error compliance and reporting          | Observability      |
-
----
-
-## Actions (Shared Verbs)
-
-These verbs have **consistent semantics** across all categories:
-
-| Verb        | Semantics                                                        | Side Effects                           |
-| ----------- | ---------------------------------------------------------------- | -------------------------------------- |
-| `discover`  | Find candidates from external sources (GitHub, filesystem, etc.) | Read-only                              |
-| `analyze`   | Compute structure, relationships, metadata                       | Read-only                              |
-| `structure` | Rewrite/normalize upstream sources to match structured spec      | **Writes** (e.g., GitHub issue bodies) |
-| `assign`    | Bind work items to workers/agents                                | **Writes** (GitHub assignees, labels)  |
-| `plan`      | Generate or inspect integration plans (only under `weave`)       | Read-only                              |
-| `run`       | Execute with side effects (gates, weaves, scans)                 | **Writes** (git, CI, GitHub)           |
-| `status`    | Show current state                                               | Read-only                              |
-| `report`    | Produce human/CI-readable summary                                | Read-only                              |
-| `init`      | Bootstrap workspace/config/profile                               | **Writes** (filesystem)                |
-| `doctor`    | Validate configuration and environment health                    | Read-only                              |
-| `migrate`   | Port existing config/state to newer shape                        | **Writes** (filesystem)                |
-
----
-
-## Examples (Canonical Intent)
-
-### Fanout Domain
-
-```bash
-lex-pr fanout discover   # Find issues eligible for fanout
-lex-pr fanout analyze    # Build structured specs from issues
-lex-pr fanout structure  # Update issue bodies to match specs
-lex-pr fanout assign     # Deterministically assign issues to workers
-lex-pr fanout report     # Summarize fanout run (who got what)
-```
-
-### Weave Domain
-
-```bash
-lex-pr weave discover    # Find PRs/branches for integration
-lex-pr weave plan        # Generate/refresh execution plan (plan.json)
-lex-pr weave run         # Execute merge pyramid with gates
-lex-pr weave status      # Show gate/merge status per node
-lex-pr weave report      # Emit integration report (Markdown/JSON)
-```
-
-### Workspace Domain
-
-```bash
-lex-pr workspace init    # Bootstrap .smartergpt.local
-lex-pr workspace doctor  # Check workspace/profile health
-lex-pr workspace migrate # Move old layout → new structure
-lex-pr workspace status  # Summarize profiles, gates, config
-```
-
-### Gate Domain
-
-```bash
-lex-pr gate run <name>       # Execute a specific gate
-lex-pr gate status [--item]  # Show gate results
-lex-pr gate report           # Aggregate pass/fail, durations
-```
-
-### Security Domain
-
-```bash
-lex-pr security analyze   # Analyze SARIF, secrets, command usage
-lex-pr security run       # Run configured scans
-lex-pr security report    # Summarize findings
-```
-
-### Safety Domain
-
-```bash
-lex-pr safety doctor   # Validate safety framework config
-lex-pr safety status   # Show kill switches, guardrails state
-```
-
-### Audit Domain
-
-```bash
-lex-pr audit report    # Summarize audit events
-lex-pr audit status    # Show audit log health
-```
-
-### AX Domain
-
-```bash
-lex-pr ax report       # Summarize AXError usage, codes
-lex-pr ax status       # Show AX compliance level
-```
-
----
-
-## Current State vs Canonical Mapping
-
-This table maps **existing commands** to their **canonical category-action** representation:
-
-| Current Command                     | Canonical Form                       | Notes                              |
-| ----------------------------------- | ------------------------------------ | ---------------------------------- |
-| `orchestrate:analyze-issues`        | `fanout analyze`                     | Issue analysis for parallelization |
-| `orchestrate:assign-batch`          | `fanout assign`                      | Deterministic worker assignment    |
-| `orchestrate:plan-batch`            | `weave discover` + `weave plan`      | PR discovery + plan generation     |
-| `orchestrate:predict-conflicts`     | `weave analyze`                      | Conflict prediction for weave      |
-| `orchestrate:generate-deliverables` | `weave report`                       | Deliverable generation             |
-| `orchestrate:pinToolchain`          | `workspace doctor` (or new category) | Toolchain validation               |
-| `init`                              | `workspace init`                     | Workspace bootstrap                |
-| `doctor`                            | `workspace doctor`                   | Health checks                      |
-| `migrateProfile`                    | `workspace migrate`                  | Profile migration                  |
-| `plan`                              | `weave plan`                         | Plan generation                    |
-| `discover`                          | `weave discover`                     | PR discovery                       |
-| `status`                            | `weave status`                       | Status reporting                   |
-| `report`                            | `weave report`                       | Report generation                  |
-
----
-
-## Implementation Strategy
-
-### Phase 1: Contract & Documentation (This PR)
-
-- ✅ Define canonical structure in this doc
-- ✅ Update help text to mention canonical forms
-- ✅ Create mapping file for current → canonical names
-
-### Phase 2: Aliases & Deprecation Warnings (Future PR)
-
-- Add canonical aliases (e.g., `lex-pr fanout analyze` as alias for `orchestrate:analyze-issues`)
-- Add deprecation warnings to old command names
-- Update all documentation to use canonical forms
-
-### Phase 3: Hard Migration (Future Major Version)
-
-- Remove deprecated command names
-- Make canonical forms the only supported interface
-- Update all examples, tests, docs
-
----
-
-## Design Rationale
-
-**Why category-action?**
-
-1. **Discoverability**: `lex-pr --help` can group by category
-2. **Consistency**: Same verbs mean the same thing everywhere
-3. **Predictability**: Users can guess command names
-4. **Extensibility**: New features fit cleanly into existing categories
-
-**Why these specific verbs?**
-
-- Chosen for **non-overlap** (each verb has distinct semantics)
-- Cover the **full lifecycle** (read-only inspection → mutation → execution)
-- Match **common patterns** in other CLIs (git, kubectl, etc.)
-
-**Why not just use `plan` as a top-level verb?**
-
-- "Plan" is too generic and appears in multiple contexts:
-  - Planning work distribution (fanout)
-  - Planning integration (weave)
-  - Planning project structure (workspace)
-- Making it a **noun** under specific categories removes ambiguity
-
----
-
-## Questions & Answers
-
-**Q: Why keep `orchestrate` for now instead of just renaming to `fanout`?**
-A: Backward compatibility. This doc establishes the contract; actual renames happen in versioned phases.
-
-**Q: Can I add new commands?**
-A: Yes, but first:
-
-1. Choose the appropriate **category**
-2. Reuse an existing **action verb** if possible
-3. Update this doc with the new mapping
-
-**Q: What if my command doesn't fit any category?**
-A: That's a signal to either:
-
-- Create a new category (requires discussion/ADR)
-- Refactor the command to fit existing categories
-- Question whether the command belongs in the CLI at all
-
----
-
-## References
-
-- [`AGENTS.md`](../AGENTS.md) - Agent operating principles
-- [`TERMS.md`](../docs/TERMS.md) - Canonical terminology
-- [`README.md`](../README.md) - User-facing command examples

package/docs/CONFLICT_DETECTION.md

@@ -1,198 +0,0 @@
-# Conflict Detection and Resolution Guidance
-
-This document describes the inter-PR conflict detection and resolution guidance feature added to the merge-weave system.
-
-## Overview
-
-During merge-weave execution, the system now detects when multiple PRs modify the same files and provides guidance on how to resolve potential conflicts. This addresses the issue encountered in Wave 2 where PRs #650 and #651 both modified `src/memory/store/tsconfig.json`, causing a merge conflict.
-
-## Features
-
-### 1. Inter-PR Conflict Detection
-
-The preflight conflict detection system now analyzes file changes across all PRs in the plan to identify overlapping modifications:
-
-- **File overlap detection**: Identifies when multiple PRs modify the same files
-- **Severity assessment**: Categorizes conflicts as "likely", "possible", or "unlikely" based on file types
-- **Pairwise analysis**: Checks every pair of PRs for potential conflicts
-
-### 2. Resolution Guidance
-
-Provides intelligent guidance for common conflict patterns:
-
-#### Auto-Merge Safe Patterns
-
-**TypeScript Config Files (`tsconfig.json`)**
-
-- **Severity**: Possible
-- **Strategy**: Merge both
-- **Guidance**: TypeScript config files typically have additive changes (includes, compiler options). Merge both additions when possible.
-- **Example**: If PR #650 adds `"src/memory/**/*"` to includes and PR #651 adds `"src/store/**/*"`, both can be merged.
-
-**Package.json**
-
-- **Severity**: Possible
-- **Strategy**: Merge both
-- **Guidance**: Package.json conflicts often involve dependencies or scripts. Review both changes and merge additive changes.
-- **Warning**: If both PRs modify the same dependency version differently, manual review required.
-
-**Lock Files**
-
-- **Severity**: Likely
-- **Strategy**: Manual (regenerate)
-- **Guidance**: Lock files should be regenerated after merge.
-- **Commands**:
-  - `package-lock.json`: `npm install`
-  - `yarn.lock`: `yarn install`
-  - `pnpm-lock.yaml`: `pnpm install`
-  - `Gemfile.lock`: `bundle install`
-  - `Cargo.lock`: `cargo update`
-  - `composer.lock`: `composer update`
-
-#### Manual Review Required
-
-**Config Files** (`.eslintrc`, `.prettierrc`, etc.)
-
-- **Severity**: Possible
-- **Strategy**: Manual
-- **Guidance**: Configuration file conflicts require review to ensure consistency.
-
-**Source Files**
-
-- **Severity**: Likely
-- **Strategy**: Manual
-- **Guidance**: Manual review recommended after the first PR merges.
-
-## Output Format
-
-### Dry-Run Output
-
-When running `lex-pr merge --dry-run`, the output now includes an "Inter-PR Conflicts" section:
-
-```
-## Inter-PR Conflicts (File Overlap)
-
-⚠️  2 potential conflict(s) between PRs detected
-
-### PR-650 ↔ PR-651
-- **Severity:** possible
-- **Overlapping files:** src/memory/store/tsconfig.json
-
-**Resolution Guidance:**
-- Type: auto-merge-safe
-- Strategy: merge-both
-- Confidence: 85%
-- TypeScript config files typically have additive changes (includes, compiler options). Merge both additions when possible.
-- **Safe merge:** Combine array entries from both sides, remove duplicates
-
-**Recommendation:** Merge PRs in dependency order and resolve conflicts as they arise.
-```
-
-## API
-
-### Types
-
-```typescript
-interface InterPRConflict {
-  /** First item involved */
-  item1: string;
-  /** Second item involved */
-  item2: string;
-  /** Conflicted file paths */
-  files: string[];
-  /** Severity: how likely this will cause a merge conflict */
-  severity: "likely" | "possible" | "unlikely";
-  /** Resolution guidance */
-  guidance?: ConflictResolutionGuidance;
-}
-
-interface ConflictResolutionGuidance {
-  /** Type of guidance */
-  type: "auto-merge-safe" | "manual-review" | "dependency-order";
-  /** Human-readable guidance message */
-  message: string;
-  /** Confidence level (0-1) */
-  confidence: number;
-  /** Suggested resolution strategy */
-  strategy?: "merge-both" | "accept-first" | "accept-last" | "manual";
-  /** Additional context */
-  context?: Record<string, unknown>;
-}
-```
-
-### Functions
-
-```typescript
-// Generate resolution guidance for a file
-function generateResolutionGuidance(filePath: string): ConflictResolutionGuidance | undefined;
-
-// Determine conflict severity
-function determineConflictSeverity(
-  file: string,
-  item1Changes: string[],
-  item2Changes: string[]
-): "likely" | "possible" | "unlikely";
-
-// Detect preflight conflicts (enhanced)
-async function detectPreflightConflicts(plan: Plan, workingDir?: string): Promise<PreflightResults>;
-```
-
-## Implementation Details
-
-### Inter-PR Conflict Detection Algorithm
-
-1. **Get changed files**: For each PR, use `git diff --name-only` to get the list of files changed compared to the target branch
-2. **Pairwise comparison**: Compare every pair of PRs to find overlapping files
-3. **Severity assessment**: For each overlapping file, determine severity based on:
-   - Lock files → "likely"
-   - Config files (tsconfig, package.json) → "possible"
-   - Other files → "likely"
-4. **Generate guidance**: Apply pattern-based rules to provide resolution hints
-
-### Resolution Guidance Patterns
-
-The system recognizes the following file patterns:
-
-- **TypeScript configs**: `/tsconfig\.json$/i`
-- **Package manifests**: `/package\.json$/i`
-- **ESLint configs**: `/\.eslintrc(\.json)?$/i`
-- **Prettier configs**: `/\.prettierrc(\.json)?$/i`
-- **Jest configs**: `/jest\.config\.(js|ts)$/i`
-- **Vitest configs**: `/vitest\.config\.(js|ts)$/i`
-- **Lock files**: Various lock file patterns
-
-## Testing
-
-The feature includes comprehensive test coverage:
-
-- **Resolution guidance tests** (`tests/resolutionGuidance.spec.ts`): 17 tests validating guidance generation for different file types
-- **Inter-PR conflict tests** (`tests/interPRConflicts.spec.ts`): Git-based integration tests (requires `LEX_GIT_MODE=live`)
-
-Run tests:
-
-```bash
-# Unit tests (no git required)
-npm test tests/resolutionGuidance.spec.ts
-
-# Integration tests (requires git)
-LEX_GIT_MODE=live npm test tests/interPRConflicts.spec.ts
-```
-
-## Future Enhancements
-
-Potential improvements for this feature:
-
-1. **Automatic conflict resolution**: For very safe patterns (e.g., non-overlapping tsconfig includes), automatically generate merged files
-2. **Dependency inference**: Automatically create dependencies when conflicts are detected (e.g., PR-651 depends on PR-650)
-3. **AI-powered guidance**: Use existing AI conflict resolution system for more complex cases
-4. **Pre-merge conflict simulation**: Run actual merge simulations to predict exact conflict locations
-
-## Related
-
-- Original issue: Wave 2 merge-weave conflict between PR #650 and #651
-- Conflicted file: `src/memory/store/tsconfig.json`
-- Related modules:
-  - `src/weave/preflightConflicts.ts`
-  - `src/weave/resolutionGuidance.ts`
-  - `src/weave/types.ts`
-  - `src/weave/mergeHelpers.ts`

package/docs/DISCIPLINED_FAILURE.md

@@ -1,224 +0,0 @@
-# Disciplined Failure Pattern
-
-> **Definition 3.4 (Disciplined Failure):** A failure mode where:
->
-> 1. Uncertainty is stated explicitly before action
-> 2. Actions taken are reversible (or flagged as non-reversible)
-> 3. Receipts document the decision chain
-> 4. Recovery path is proposed or escalation triggered
-
-This document describes the Disciplined Failure pattern implemented in lexrunner, extending the AXError pattern with governance fields for reversibility, confidence, and action receipts.
-
-## Overview
-
-The Disciplined Failure pattern enables agents to:
-
-- **Fail safely**: Actions are classified by reversibility
-- **Fail transparently**: Uncertainty is declared before action
-- **Fail traceably**: ActionReceipts document the decision chain
-- **Fail recoverably**: Recovery paths are always proposed
-
-## Components
-
-### 1. ActionReceipt
-
-An ActionReceipt documents every significant action with full context:
-
-```typescript
-import { emitActionReceipt } from "../src/receipts/index.js";
-
-emitActionReceipt({
-  action: "merge PR-123 to integration",
-  rationale: "PR dependencies satisfied, gates green",
-  confidence: "high",
-  reversibility: "reversible",
-  rollbackPath: "git reset --hard HEAD~1",
-  phase: "apply",
-});
-```
-
-**Output:**
-
-```json
-{
-  "event": "action_receipt",
-  "schemaVersion": "1.0.0",
-  "kind": "ActionReceipt",
-  "action": "merge PR-123 to integration",
-  "outcome": "success",
-  "rationale": "PR dependencies satisfied, gates green",
-  "confidence": "high",
-  "reversibility": "reversible",
-  "rollbackPath": "git reset --hard HEAD~1",
-  "escalationRequired": false,
-  "timestamp": "2024-01-15T10:30:00.000Z",
-  "phase": "apply"
-}
-```
-
-### 2. UncertaintyMarker
-
-Before taking a risky action, declare uncertainty explicitly:
-
-```typescript
-import { emitUncertaintyMarker } from "../src/receipts/index.js";
-
-emitUncertaintyMarker({
-  operation: "merge PR-456 with active dependencies",
-  uncertainties: [
-    "Dependency PR-123 may have untested changes",
-    "Target branch received commits since last check",
-  ],
-  mitigations: ["Will run full test suite after merge", "Rollback path: git reset --hard HEAD~1"],
-  proceedingAnyway: true,
-  reason: "Time-sensitive release; risk accepted by policy",
-});
-```
-
-### 3. Governance Context for AXError
-
-Extend AXError with governance fields via the context object:
-
-```typescript
-import { buildGovernanceContext } from "../src/receipts/index.js";
-import { createAXError } from "../src/errors/index.js";
-
-const govCtx = buildGovernanceContext({
-  reversibility: "reversible",
-  rollbackPath: "git reset --hard HEAD~1",
-  confidence: "high",
-});
-
-const error = createAXError(
-  "MERGE_CONFLICT",
-  "Merge conflict detected in src/cli.ts",
-  ["Resolve conflicts manually", "Re-run merge"],
-  { ...otherContext, ...govCtx }
-);
-```
-
-## Reversibility Levels
-
-| Level                  | Description                | Example                   |
-| ---------------------- | -------------------------- | ------------------------- |
-| `reversible`           | Action can be fully undone | Git merge (can reset)     |
-| `partially-reversible` | Some effects persist       | Branch creation + commits |
-| `irreversible`         | Cannot be undone           | Published release         |
-
-## Confidence Levels
-
-| Level       | Description                   | When to Use                        |
-| ----------- | ----------------------------- | ---------------------------------- |
-| `high`      | Strong expectation of success | Dependencies verified, gates green |
-| `medium`    | Reasonable expectation        | Most dependencies ready            |
-| `low`       | Uncertain outcome             | Some unknowns present              |
-| `uncertain` | Unknown outcome               | Experimental or new path           |
-
-## Integration Points
-
-### Merge-Weave Operations
-
-```typescript
-// In src/weave/execute.ts
-import { emitActionReceipt, emitUncertaintyMarker } from "../receipts/index.js";
-
-// Before merge
-emitUncertaintyMarker({
-  operation: `merge ${pr.branch} to integration`,
-  uncertainties: conflicts.length > 0 ? [`${conflicts.length} potential conflicts detected`] : [],
-  mitigations: ["Pre-flight conflict detection", "Rollback available"],
-  proceedingAnyway: true,
-  reason: "Conflicts can be resolved during merge",
-});
-
-// After merge
-emitActionReceipt({
-  action: `merge PR-${pr.number} to integration`,
-  rationale: "Dependencies satisfied, gates green",
-  confidence: "high",
-  reversibility: "reversible",
-  rollbackPath: `git reset --hard ${previousHead}`,
-  phase: "apply",
-  runId: context.runId,
-  planHash: context.planHash,
-});
-```
-
-### Gate Execution
-
-```typescript
-// In src/gates/run.ts
-import { emitActionReceipt } from "../receipts/index.js";
-
-// After gate execution
-emitActionReceipt({
-  action: `execute gate: ${gate.name}`,
-  rationale: "Required by plan policy",
-  confidence: "high",
-  reversibility: "reversible", // Gates don't mutate state
-  outcome: gate.passed ? "success" : "failure",
-  nextActions: gate.passed ? ["Continue to next gate"] : ["Fix gate failures", "Re-run gate"],
-  phase: "verify",
-});
-```
-
-## Schema Reference
-
-### ActionReceipt
-
-| Field                | Type                                                 | Required             | Description             |
-| -------------------- | ---------------------------------------------------- | -------------------- | ----------------------- |
-| `schemaVersion`      | `"1.0.0"`                                            | Yes                  | Schema version          |
-| `kind`               | `"ActionReceipt"`                                    | Yes                  | Receipt type            |
-| `action`             | `string`                                             | Yes                  | Description of action   |
-| `outcome`            | `success \| failure \| partial \| deferred`          | Yes                  | Result                  |
-| `rationale`          | `string`                                             | Yes                  | Why action was taken    |
-| `confidence`         | `high \| medium \| low \| uncertain`                 | Yes                  | Confidence level        |
-| `reversibility`      | `reversible \| partially-reversible \| irreversible` | Yes                  | Rollback capability     |
-| `rollbackPath`       | `string`                                             | No                   | Rollback instructions   |
-| `rollbackCommand`    | `string`                                             | No                   | Actual rollback command |
-| `nextActions`        | `string[]`                                           | No                   | Suggested next steps    |
-| `escalationRequired` | `boolean`                                            | Yes (default: false) | Needs human review      |
-| `escalationReason`   | `string`                                             | No                   | Why escalation needed   |
-| `uncertaintyNotes`   | `string[]`                                           | No                   | Known uncertainties     |
-| `timestamp`          | `string (ISO 8601)`                                  | Yes                  | When action occurred    |
-| `phase`              | `string`                                             | No                   | Execution phase         |
-| `runId`              | `string`                                             | No                   | Correlation ID          |
-| `planHash`           | `string`                                             | No                   | Plan verification       |
-
-### UncertaintyMarker
-
-| Field              | Type                | Required | Description        |
-| ------------------ | ------------------- | -------- | ------------------ |
-| `operation`        | `string`            | Yes      | Planned operation  |
-| `uncertainties`    | `string[]`          | Yes      | Known unknowns     |
-| `mitigations`      | `string[]`          | Yes      | Risk mitigations   |
-| `proceedingAnyway` | `boolean`           | Yes      | Whether to proceed |
-| `reason`           | `string`            | No       | Why proceeding     |
-| `timestamp`        | `string (ISO 8601)` | No       | Declaration time   |
-
-## Best Practices
-
-1. **Always emit receipts for mutations**: Any action that changes state should emit a receipt.
-
-2. **Declare uncertainty early**: Use UncertaintyMarker before risky operations.
-
-3. **Include rollback paths**: Every reversible action should specify how to undo it.
-
-4. **Escalate appropriately**: Set `escalationRequired: true` when human judgment is needed.
-
-5. **Correlate with run context**: Include `runId` and `planHash` for traceability.
-
-## Cross-References
-
-- [AXError Pattern](./errors.md) - Base error handling
-- [Merge-Weave State Machine](./merge-weave-state-machine.md) - Weave execution
-- [Gates Documentation](./gates.md) - Gate execution
-
-## Governance Alignment
-
-This pattern implements Definition 3.4 (Disciplined Failure) from the coordination cost compression thesis, connecting to:
-
-- **Receipt Protocol Schema** - Standardized action documentation
-- **AXError Pattern** - Recoverable error handling with `nextActions`
-- **Permission to Fail** - Bounded autonomy with accountability