@smartergpt/lexrunner 1.0.0

package/docs/CLI_VERBS.md

@@ -0,0 +1,219 @@
+# 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

@@ -0,0 +1,198 @@
+# 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

@@ -0,0 +1,224 @@
+# 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