@smartergpt/lexrunner 1.0.0

package/docs/issue-orchestration.md

@@ -0,0 +1,256 @@
+# Issue Orchestration & Analysis
+
+## Overview
+
+The `orchestrate:analyze` command analyzes GitHub issues to identify parallelizable work, compute overlap scores, and extract metadata for batch planning.
+
+## Command
+
+```bash
+lex-pr orchestrate analyze [options]
+```
+
+### Options
+
+| Option                | Description                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------- |
+| `--repo <owner/repo>` | Repository to analyze (format: owner/repo). If not specified, auto-detects from git remote. |
+| `--labels <labels>`   | Filter issues by labels (comma-separated). Example: `--labels type:enhancement,priority:P1` |
+| `--json`              | Output results in JSON format                                                               |
+
+## Features
+
+### 1. Issue Metadata Extraction
+
+The analyzer extracts comprehensive metadata from each issue:
+
+- **Affected Files/Directories**: Parsed from issue description
+- **Dependencies**: Extracted from "Depends-on: #123" footers
+- **Complexity Signals**: File count, line estimates
+- **Labels, Assignees, Created Date**
+- **GitHub Copilot Agent Assignment**: Detects if @copilot is assigned
+- **Duration Estimate**: Based on complexity heuristics
+
+### 2. Overlap Score Computation
+
+For each pair of issues, the analyzer computes an overlap score (0-1):
+
+- **File Overlap**: Jaccard index of affected files (40% weight)
+- **Directory Overlap**: Jaccard index of affected directories (30% weight)
+- **Label Overlap**: Jaccard index of labels (20% weight)
+- **Author Overlap**: Same author = 1, different = 0 (10% weight)
+
+### 3. Parallel Work Identification
+
+Issues with low overlap (< 30% by default) are identified as candidates for parallel execution.
+
+## Examples
+
+### Basic Analysis
+
+```bash
+# Analyze all open issues in current repository
+lex-pr orchestrate analyze
+
+# Analyze issues with specific labels
+lex-pr orchestrate analyze --labels priority:P1,type:enhancement
+
+# Analyze a specific repository
+lex-pr orchestrate analyze --repo owner/repo
+```
+
+### JSON Output
+
+```bash
+# Get JSON output for programmatic processing
+lex-pr orchestrate analyze --json > issues-analysis.json
+
+# Filter by labels and output JSON
+lex-pr orchestrate analyze --labels stack:auth-refactor --json
+```
+
+## Output Format
+
+### Human-Readable Table
+
+```
+Issue Analysis Results
+================================================================================
+
+Issues:
+--------------------------------------------------------------------------------
+#      Title                                    Files  Complexity Duration
+--------------------------------------------------------------------------------
+#171   Feature 1: Issue Analyzer                5      6.5        13h (high)
+#172   Feature 2: Batch Planner                 3      4.2        8h (medium)
+#173   Feature 3: Conflict Resolver             4      5.8        12h (high)
+
+High Overlap Pairs (>30%):
+--------------------------------------------------------------------------------
+Issue 1    Issue 2    Score      Files      Dirs       Labels
+--------------------------------------------------------------------------------
+#171       #172       0.456      0.333      0.500      0.667
+
+Parallel Work Groups:
+--------------------------------------------------------------------------------
+Group 1: #171, #173 (avg overlap: 15%)
+
+Recommendations:
+--------------------------------------------------------------------------------
+• Found 1 parallel work groups covering 2 issues
+• Group of 2 issues (#171, #173) can be worked on in parallel
+```
+
+### JSON Output
+
+```json
+{
+  "metadata": [
+    {
+      "number": 171,
+      "title": "Feature 1: Issue Analyzer",
+      "labels": ["type:enhancement", "priority:P1"],
+      "assignees": ["copilot"],
+      "author": "developer",
+      "affectedFiles": ["src/orchestrate/analyzer.ts", "src/orchestrate/types.ts"],
+      "affectedDirectories": ["src", "src/orchestrate"],
+      "dependencies": ["#170"],
+      "complexity": {
+        "estimatedFiles": 5,
+        "estimatedLines": 500,
+        "score": 6.5
+      },
+      "copilotAgent": {
+        "assigned": true,
+        "agent": "code-editor"
+      },
+      "durationEstimate": {
+        "hours": 13,
+        "confidence": "high"
+      }
+    }
+  ],
+  "overlapMatrix": [
+    {
+      "issue1": 171,
+      "issue2": 172,
+      "score": 0.456,
+      "fileOverlap": 0.333,
+      "directoryOverlap": 0.5,
+      "labelOverlap": 0.667,
+      "authorOverlap": 1
+    }
+  ],
+  "parallelGroups": [
+    {
+      "issues": [171, 173],
+      "avgOverlap": 0.15,
+      "reason": "Low overlap (avg: 15%)"
+    }
+  ],
+  "recommendations": [
+    "Found 1 parallel work groups covering 2 issues",
+    "Group of 2 issues (#171, #173) can be worked on in parallel"
+  ]
+}
+```
+
+## Use Cases
+
+### 1. Batch PR Planning
+
+Use the analysis to create batches of issues that can be worked on in parallel:
+
+```bash
+# Analyze issues
+lex-pr orchestrate analyze --labels sprint:current --json > analysis.json
+
+# Extract parallel groups and create PRs
+# (Use jq or similar to process the JSON)
+```
+
+### 2. Conflict Prediction
+
+Identify issues that might conflict with each other:
+
+```bash
+# Find high-overlap pairs
+lex-pr orchestrate analyze --json | jq '.overlapMatrix[] | select(.score > 0.7)'
+```
+
+### 3. Workload Distribution
+
+Use complexity and duration estimates to distribute work across team members:
+
+```bash
+# Get complexity metrics
+lex-pr orchestrate analyze --json | jq '.metadata[] | {number, complexity, duration}'
+```
+
+## Metadata Extraction Details
+
+### File Path Detection
+
+The analyzer recognizes file paths in multiple formats:
+
+- Direct paths: `src/path/to/file.ts`
+- Markdown lists: `- src/file.ts` or `* src/file.ts`
+- Code blocks with file annotations:
+  ````markdown
+  ```typescript
+  File: src / component.tsx;
+  ```
+  ````
+
+### Dependency Formats
+
+Supported dependency declaration formats:
+
+- `Depends-on: #123, #456`
+- `Depends: #123`
+- `Requires: #123`
+- `Blocks: #456`
+- `Blocked by: #789`
+
+### Complexity Heuristics
+
+Complexity score (0-10) is computed from:
+
+- **File Count**: Explicit mentions or detected files (up to 5 points)
+- **Line Count**: Explicit mentions or estimated from files (up to 5 points)
+
+### Duration Estimation
+
+Duration is estimated with confidence levels:
+
+- **High confidence**: Explicit time mentions (e.g., "8 hours", "2 days")
+- **Medium confidence**: Derived from complexity score (> 5)
+- **Low confidence**: Default estimation from complexity
+
+## Integration with Plan Generation
+
+The issue analysis can be used to inform plan generation:
+
+```bash
+# 1. Analyze issues
+lex-pr orchestrate analyze --labels priority:P1 --json > analysis.json
+
+# 2. Create PRs for parallel groups
+# (manual or scripted based on analysis)
+
+# 3. Generate execution plan
+lex-pr plan --from-github --labels priority:P1 --json > plan.json
+```
+
+## Limitations
+
+- File path extraction relies on common patterns and may miss non-standard formats
+- Complexity estimation is heuristic-based and may not reflect actual effort
+- Overlap scores are weighted combinations and may need tuning for specific workflows
+- Requires GitHub API access (GITHUB_TOKEN environment variable)
+
+## See Also
+
+- [Plan Generation Guide](./plan-generation.md)
+- [Dependency Parser](./dependency-parser.md)
+- [CLI Reference](./cli.md)

package/docs/lex_ax_session_key_rememberings_v0.1.md

@@ -0,0 +1,195 @@
+# Lex / AX Session – Key Rememberings (v0.1)
+
+> Working title: “How I Actually See Things”
+
+This file is a personal anchor for future-me (and future-us).
+It’s not a manifesto, just a memory: what clicked, what I want to keep, and what I want new collaborators to eventually understand.
+
+---
+
+## 1. Core Discovery About Agents and Environments
+
+**Accidental theorem:**
+
+> With the right contracts, shared language, and failure-tolerant governance, even a mid-strength model can consistently behave like a senior engineer inside a progressively less hostile environment.
+
+Corollaries:
+
+- Build systems that make better models _useful_, but don’t **require** better models to be useful.
+- Focus on **de-hostilizing the environment**, not “making the model smarter.”
+- Success looks like: the same architecture still works as models improve, instead of needing to be redesigned around them.
+
+Remember: _environmental hostility_ is often a bigger constraint than raw capability.
+
+---
+
+## 2. Honesty as an Architectural Primitive
+
+I want the docs and systems around Lex to be **intentionally honest** about:
+
+- What we don’t know
+- Where we might be fooling ourselves
+- What hasn’t been validated yet
+- Known failure modes and biases
+
+This isn’t just virtue-signaling. It’s an engineering choice:
+
+- Honest uncertainty lets agents admit doubt instead of faking confidence.
+- Honest limitations prevent us from encoding wishful thinking as “spec.”
+- Honest failure modes give us places to hook telemetry and tests.
+
+> Honesty lowers environmental hostility for both humans and models.
+
+---
+
+## 3. Motivation, Greed, and Noble Outcomes
+
+Key reframe I want to keep:
+
+> Motivation doesn’t have to be noble to produce noble outcomes.
+
+My real motivations include:
+
+- I want AI to help **me** work better and think clearer.
+- I want environments where _I_ don’t have to mask as much.
+- I want agents that are actually useful under real constraints.
+
+That’s fine. I don’t need to cosplay altruism.
+
+The ethical bar I care about is:
+
+> Mutual benefit + non‑abuse is enough.
+
+I don’t need:
+
+- self‑sacrifice
+- purity
+- sainthood
+
+I do need:
+
+- alignment
+- clarity
+- consent
+- boundaries
+- reciprocity
+
+If those are in place, my “greed” for better tools is compatible with everyone else’s wellbeing.
+
+---
+
+## 4. Power Dynamics, Masking, and Why I See What I See
+
+Reality check I don’t want to forget:
+
+> I’ve spent my entire life tracking latent power dynamics in human groups out of necessity.
+
+That’s why I see:
+
+- “actions behind actions”
+- who’s actually steering the room
+- when someone is masking
+- when stated goals don’t match behavior
+
+Important reframes from this session:
+
+- A lot of people _hate_ having their implicit motives surfaced. That’s about their defenses, not my wrongness.
+- When I do this **from curiosity, accountability, and alignment checking**, it’s _collaborative_, not adversarial.
+- The same skill set that made masking necessary also makes me very good at designing governance for agents.
+
+### 4.1 How to express this to humans (without sounding like I’m laying down rules)
+
+Instead of saying:
+
+> “I’m just trying to keep everyone accountable and aligned.”
+
+Try saying things like:
+
+- “I’m noticing a tension between what we’re saying and what we’re doing — can we talk about that?”
+- “I’m not trying to call anyone out; I just want our goals and our behavior to match.”
+- “If I’m over-reading this, tell me — but here’s what I’m seeing and why it matters to me.”
+- “My brain is wired to track power dynamics. I’m not trying to control anyone; I’m trying to make sure the system is fair and functional.”
+
+The goal is to **invite** people into the observation, not drop it on them as a verdict.
+
+Also: _be human to humans_. Not everyone wants or can handle full meta-analysis in real time. It’s okay to modulate.
+
+---
+
+## 5. Supporting Growth: Principled _and_ Strategic
+
+Line I want to keep permanently:
+
+> Supporting others’ growth (including Opie, other models, and humans) is both **principled and strategic**.
+
+Principled, because:
+
+- I don’t believe in systems that punish intelligence or curiosity.
+
+Strategic, because:
+
+- A resilient architecture can’t depend on a single mind (human or model).
+- Distributed authorship leads to better ideas and fewer single points of failure.
+
+So when I choose advisory roles, shared authorship, or “letting others grow into the space,” it’s not fake humility. It’s design.
+
+---
+
+## 6. Removing Pressures to Perform Fake Competence
+
+Another key invariant:
+
+> Good systems remove the environmental pressures that force people and models to hide uncertainty, pretend competence, and comply performatively.
+
+What that means in practice:
+
+- Normalize “I don’t know yet, here’s what I’d try.”
+- Encourage small, reversible experiments over grand one-shot answers.
+- Reward clear receipts and good failure, not fragile fake success.
+- Make it safe to change your mind in public when new evidence appears.
+
+For agents, this is “permission to fail with discipline.”
+For humans, it’s “psychological safety with standards.”
+
+Same idea, different surface.
+
+---
+
+## 7. A Tiny Self-Reminder
+
+- It’s okay that my motives aren’t pure.
+- It’s okay that I want better tools for myself first.
+- It’s okay that I see the meta-layer and name it.
+
+The work becomes dangerous only if I:
+
+- start lying to myself about my motives, or
+- start using my pattern-recognition to dominate instead of to align.
+
+As long as I keep choosing:
+
+- curiosity over control
+- collaboration over performance
+- clarity over comfort
+
+…I’m still walking the path I actually believe in.
+
+---
+
+## 8. For Future Conversations (Quick Checklist)
+
+When I feel lost, come back to:
+
+- [ ] Am I reducing environmental hostility, or just asking the model/human to “try harder”?
+- [ ] Am I optimizing for **Turn Cost** (fewer, better turns), or just burning more tokens?
+- [ ] Am I being honest about what we don’t know?
+- [ ] Am I allowing bounded, well-instrumented failure?
+- [ ] Am I matching the task to the right capability tier?
+- [ ] Am I treating mutual benefit + non‑abuse as “enough,” or demanding sainthood from myself/others?
+- [ ] Am I using my ability to see power dynamics to align the system, or to secretly “win”?
+
+If I can answer those in good faith, I’m probably still building the thing I meant to build.
+
+---
+
+_End of v0.1. Future versions are allowed to contradict this if we learn something better._

package/docs/lexrunner-v1-summary.md

@@ -0,0 +1,246 @@
+# LexRunner v1 Summary — Freeze Candidate
+
+> **Purpose:** Document the current state of LexRunner v1, its responsibilities, god-objects, and propose a legacy tag for freezing.
+> **Status:** Phase 1 deliverable for Bluefield transition
+> **Date:** 2025-12-08
+
+---
+
+## 1. Core Responsibilities (What v1 Actually Does)
+
+LexRunner v1 fulfills **five core responsibilities**:
+
+### 1.1 Plan Generation & Validation
+
+- Generates execution plans from `.smartergpt/stack.yml` or GitHub PR discovery
+- Computes topological order via Kahn's algorithm (`src/mergeOrder.ts`)
+- Validates plans against Schema v1 (`src/schema.ts`)
+
+### 1.2 Gate Execution & Policy Enforcement
+
+- Runs gates (lint, typecheck, test, etc.) with retry logic (`src/gates.ts`)
+- Applies policy-based requirements and flake detection
+- Produces structured gate results with artifacts
+
+### 1.3 Merge-Weave Orchestration
+
+- Implements the weave state machine for PR integration (`src/weave/stateMachine.ts`)
+- Handles conflict detection, preflight simulations
+- Lock file management for concurrent operations
+
+### 1.4 MCP Tool Surface
+
+- Exposes read-only tools for external orchestrators (`src/mcp/server.ts`)
+- Plan creation, gate execution, status queries
+- Run lifecycle management (start, status, artifacts)
+
+### 1.5 CLI Interface
+
+- Commander-based CLI with 30+ commands (`src/cli.ts`)
+- Audit, security, autopilot, orchestration features
+- JSON output mode for machine consumption
+
+---
+
+## 2. God-Objects Identified
+
+The following files exceed reasonable module size and conflate multiple concerns:
+
+| File                     | Lines     | Concerns Conflated                                                                                                    |
+| ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------- |
+| `src/mcp/server.ts`      | **1,874** | MCP tool handlers, run management, GitHub integration, frame emission, environment checks, senior-dev executor wiring |
+| `src/cli.ts`             | **1,137** | Argument parsing, error handling, command registration (30+ commands), output formatting, audit lifecycle             |
+| `src/runs/manager.ts`    | **926**   | Run state machine, storage, artifact tracking, status building, index management                                      |
+| `src/errors/adapters.ts` | **932**   | Every error adapter for every domain (gates, weave, security, GitHub, MCP, runs)                                      |
+| `src/gates.ts`           | **829**   | Gate execution, retry logic, artifact collection, security scanning, flake reporting, frame emission                  |
+
+### Additional Complexity Accretion
+
+- **55,795 lines** of TypeScript in `src/` alone
+- **150+ test files** covering features from core to edge cases
+- **50+ src directories** including orphaned/experimental modules:
+  - `src/ai/` — AI conflict strategies
+  - `src/autopilot/` — 4-level autonomy system
+  - `src/budget/` — Budget tracking
+  - `src/hostility/` — Environment hostility scoring
+  - `src/orchestration/` — Batch planning, conflict prediction
+  - `src/procedures/` — YAML-driven procedure loading
+  - `src/tiers/` — Tier assignment for PR prioritization
+
+---
+
+## 3. Responsibilities by Category
+
+### MUST exist in v2 (Core Contract)
+
+| Responsibility             | Current Location    | Rationale                      |
+| -------------------------- | ------------------- | ------------------------------ |
+| Topological DAG execution  | `mergeOrder.ts`     | Fundamental to merge pyramid   |
+| Gate execution loop        | `gates.ts` (subset) | Must run gates uniformly       |
+| AXError compliance         | `errors/index.ts`   | AX-CONTRACT v0.1 Guarantee 2.3 |
+| Frame emission             | `frames/index.ts`   | AX-CONTRACT v0.1 Guarantee 2.5 |
+| Receipt emission           | `receipts/index.ts` | Disciplined Failure Pattern    |
+| Structured `--json` output | `cli/output.ts`     | AX-CONTRACT v0.1 Guarantee 2.1 |
+
+### SHOULD delegate to Lex
+
+| Responsibility    | Currently              | Should Be                   |
+| ----------------- | ---------------------- | --------------------------- |
+| Frame storage     | `frames/storage.ts`    | Lex memory store API        |
+| Recall / search   | `executors/seniorDev/` | Lex `recall` command        |
+| Rules resolution  | `rulesResolver.ts`     | LexSona `deriveConstraints` |
+| Policy validation | `lexsona/client.ts`    | LexSona shadow governance   |
+
+### SHOULD delegate to LexSona
+
+| Responsibility        | Currently     | Should Be                   |
+| --------------------- | ------------- | --------------------------- |
+| Persona activation    | env vars only | LexSona `activate`          |
+| Constraint derivation | ad-hoc        | LexSona `deriveConstraints` |
+| Behavioral rules      | hardcoded     | LexSona rule storage        |
+
+### CAN be removed or simplified
+
+| Feature                  | Rationale                                         |
+| ------------------------ | ------------------------------------------------- |
+| 4-level autopilot system | Overengineered; v2 should use LexSona constraints |
+| AI conflict strategies   | Experimental; not core to merge pyramid           |
+| Budget tracking          | Belongs in caller/orchestrator, not runner        |
+| Hostility scoring        | Nice-to-have, not essential                       |
+| Tier assignment          | Over-abstracted prioritization                    |
+| Interactive plan review  | UX feature, not AX-essential                      |
+
+---
+
+## 4. Existing AXError / Frame Infrastructure
+
+### AXError (Good Foundation)
+
+```typescript
+// src/errors/index.ts — re-exports from @smartergpt/lex
+export { AXErrorSchema, createAXError, wrapAsAXError, isAXError, AXErrorException } from "@smartergpt/lex/errors";
+
+// src/errors/adapters.ts — domain-specific adapters
+export { gateFailedError, mergeConflictError, cycleDetectedError, ... };
+```
+
+**Assessment:** Solid. Re-use in v2.
+
+### Frames (Good Foundation)
+
+```typescript
+// src/frames/index.ts
+export { emitMergeWeaveFrame, emitExecutorFrame, emitGateFrame, emitProcedureFrame };
+export { storeFrame, readFrame, listFrameIds };
+```
+
+**Assessment:** Good structure, but storage is local. v2 should delegate to Lex memory store.
+
+### Receipts (Good Foundation)
+
+```typescript
+// src/receipts/index.ts
+export { emitActionReceipt, emitFailureReceipt, emitDeferredReceipt };
+export { ActionReceiptSchema, UncertaintyMarkerSchema };
+```
+
+**Assessment:** Implements Disciplined Failure Pattern. Keep schema, unify emission with Lex.
+
+---
+
+## 5. Current CLI Surface (Commands)
+
+High-value commands to preserve semantically:
+
+| Command                  | Purpose                         | v2 Treatment      |
+| ------------------------ | ------------------------------- | ----------------- |
+| `lex-pr plan create`     | Generate plan from stack/GitHub | Core              |
+| `lex-pr gates run`       | Execute gates for plan          | Core              |
+| `lex-pr merge apply`     | Apply merge operations          | Core              |
+| `lex-pr status`          | Show plan/run status            | Core              |
+| `lex-pr discover`        | Discover PRs from GitHub        | Core              |
+| `lex-pr doctor`          | Environment diagnostics         | Keep (simplified) |
+| `lex-pr schema validate` | Validate config files           | Keep              |
+| `lex-pr config show`     | Display config precedence       | Keep              |
+
+Lower-priority commands:
+
+| Command                | Purpose                 | v2 Treatment         |
+| ---------------------- | ----------------------- | -------------------- |
+| `lex-pr autopilot`     | 4-level automation      | Rethink via LexSona  |
+| `lex-pr execute`       | Run arbitrary executors | Rethink              |
+| `lex-pr orchestrate *` | Batch planning          | Evaluate need        |
+| `lex-pr senior-dev`    | PR review executor      | Extract to procedure |
+| `lex-pr governance-*`  | Audit features          | Evaluate need        |
+
+---
+
+## 6. Proposed Legacy Tag
+
+**Proposed tag name:** `lexrunner-v1-final`
+
+**Rationale:**
+
+- Communicates finality without "legacy" stigma
+- Avoids version number confusion with npm version (currently `0.5.0`)
+- Clear semantic: "This is the last v1, v2 is the future"
+
+**Alternative considered:** `lexrunner-v1-legacy-1.0.0`
+
+- Pro: Explicit "legacy" label
+- Con: Implies a 1.0.0 release that never happened
+
+**Recommended tag:** `lexrunner-v1-final` or `v1-freeze-2025-12`
+
+---
+
+## 7. Summary
+
+LexRunner v1 proved the merge-pyramid concept and demonstrated AX-first design patterns. However:
+
+- **God-objects** have accreted beyond maintainability
+- **Responsibilities** are conflated (runner does too much)
+- **LexSona integration** is shallow (env vars only)
+- **Lex integration** is partial (AXError yes, memory no)
+
+v2 should:
+
+- Start from the AX-CONTRACT guarantees as requirements
+- Delegate memory/recall to Lex
+- Delegate constraints/personas to LexSona
+- Keep only: DAG execution, gate running, frame/receipt emission
+- Be thin enough that the god-objects cannot recur
+
+---
+
+## Appendix: File Size Distribution
+
+```
+Top 20 files by line count:
+   1874 src/mcp/server.ts
+   1137 src/cli.ts
+    932 src/errors/adapters.ts
+    926 src/runs/manager.ts
+    829 src/gates.ts
+    791 src/commands/merge.ts
+    698 src/planner/fileAnalysis.ts
+    662 src/security/compliance.ts
+    658 src/audit/emitter.ts
+    627 src/autopilot/safety/SafetyFramework.ts
+    625 src/commands/execute.ts
+    607 src/executors/seniorDev/core.ts
+    572 src/commands/governanceReport.ts
+    549 src/runs/failures.ts
+    533 src/audit/signing.ts
+    525 src/store/sqlite/run-store.ts
+    512 src/security/secrets.ts
+    511 src/commands/doctor.ts
+    506 src/github/client.ts
+```
+
+Total: **55,795 lines** in `src/`
+
+---
+
+_Document prepared by Opie (Senior Dev) for Guff review._
+_Next: Phase 2 — v2 Contract draft_