@smartergpt/lexrunner 1.0.0

package/docs/architecture.md

@@ -0,0 +1,316 @@
+# Architecture Overview
+
+## Design Philosophy
+
+lexrunner is built on three core principles:
+
+### 1. **Determinism First**
+
+- Same inputs → identical outputs (byte-for-byte)
+- No timestamps, random ordering, or non-deterministic behavior
+- Canonical JSON with stable key ordering
+- Cross-platform portability (Windows, macOS, Linux)
+
+### 2. **Two-Track Separation**
+
+- **Core Runner** (`src/**`): CLI logic, never stores user/work artifacts
+- **Workspace Profile** (`.smartergpt/**`): Portable configuration and examples
+- Clear boundary prevents mixing code and data
+
+### 3. **Local-First Operations**
+
+- All operations run locally with no server dependencies
+- Privacy-first: no secrets in artifacts
+- GitHub API calls only for discovery, not execution
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    lexrunner                        │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  ┌──────────────┐         ┌──────────────┐            │
+│  │  Runner CLI  │────────▶│  MCP Server  │            │
+│  │   (TypeScript)│         │  (Adapter)   │            │
+│  └──────────────┘         └──────────────┘            │
+│         │                         │                     │
+│         ▼                         ▼                     │
+│  ┌──────────────────────────────────────┐              │
+│  │         Core Components               │              │
+│  ├──────────────────────────────────────┤              │
+│  │  • Plan Generator                     │              │
+│  │  • Dependency Resolver                │              │
+│  │  • Gate Executor                      │              │
+│  │  • Merge Coordinator                  │              │
+│  │  • GitHub Integration                 │              │
+│  └──────────────────────────────────────┘              │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+              ┌───────────────────────┐
+              │  Workspace Profile    │
+              ├───────────────────────┤
+              │  • intent.md          │
+              │  • scope.yml          │
+              │  • deps.yml           │
+              │  • gates.yml          │
+              │  • profile.yml        │
+              └───────────────────────┘
+```
+
+## Core Components
+
+### Runner CLI (`src/cli.ts`)
+
+The primary command-line interface built with Commander.js.
+
+**Key Commands:**
+
+- `init` - Initialize workspace
+- `discover` - Find PRs from GitHub
+- `plan` - Generate merge plan
+- `execute` - Run quality gates
+- `merge` - Execute merge operations
+- `doctor` - Environment validation
+
+### Plan Generator (`src/core/plan.ts`)
+
+Creates merge plans from configuration and GitHub data.
+
+**Inputs:**
+
+- `scope.yml` - PR selection criteria
+- `deps.yml` - Dependency definitions
+- GitHub API - Live PR data
+
+**Output:**
+
+- `plan.json` - Structured merge plan with dependency graph
+
+### Dependency Resolver (`src/mergeOrder.ts`)
+
+Computes topologically sorted merge order using Kahn's algorithm.
+
+**Features:**
+
+- Cycle detection
+- Parallel execution opportunities
+- Deterministic ordering (alphabetical tiebreaker)
+
+### Gate Executor (`src/gates.ts`)
+
+Runs quality gates with dependency-aware execution.
+
+**Capabilities:**
+
+- Parallel execution where possible
+- Exit code/duration/stdout/stderr capture
+- JSON output with stable schema
+- Policy-based evaluation
+
+### GitHub Integration (`src/github/`)
+
+Read-only GitHub API client for PR discovery.
+
+**Operations:**
+
+- List open pull requests
+- Fetch PR metadata (title, author, labels)
+- Branch information
+- No write operations (safety)
+
+### MCP Server (`src/mcp/server.ts`)
+
+Optional Model Context Protocol adapter.
+
+**Exposed Tools:**
+
+- `plan.create` - Generate merge plan
+- `gates.run` - Execute quality gates
+- `merge.apply` - Perform merge operations
+
+**Resources:**
+
+- `.smartergpt/runner/*` - Read-only access to artifacts
+
+## Data Flow
+
+### 1. Discovery Phase
+
+```
+GitHub API → discover → PRs list
+                ↓
+         scope.yml filtering
+                ↓
+         Filtered PR set
+```
+
+### 2. Planning Phase
+
+```
+Filtered PRs + deps.yml → Plan Generator
+                ↓
+         Dependency graph construction
+                ↓
+         Topological sort
+                ↓
+         plan.json (with merge order)
+```
+
+### 3. Execution Phase
+
+```
+plan.json + gates.yml → Gate Executor
+                ↓
+         Run gates in dependency order
+                ↓
+         Collect results
+                ↓
+         gate-results/*.json
+```
+
+### 4. Merge Phase
+
+```
+plan.json + gate results → Merge Coordinator
+                ↓
+         Validate all gates pass
+                ↓
+         Execute git operations
+                ↓
+         Merge PRs in order
+```
+
+## Configuration Resolution
+
+### Profile Directory Precedence
+
+1. `--profile-dir <path>` - Explicit CLI override
+2. `LEX_PR_PROFILE_DIR` - Environment variable
+3. `.smartergpt.local/` - Local overlay (not tracked)
+4. `.smartergpt/` - Example profile (tracked, default)
+
+See [profile-resolution.md](./profile-resolution.md) for details.
+
+### Configuration Files
+
+| File          | Purpose                       | Priority   |
+| ------------- | ----------------------------- | ---------- |
+| `stack.yml`   | Explicit plan with items/deps | Highest    |
+| `scope.yml`   | PR selection criteria         | Fallback   |
+| `deps.yml`    | Dependency definitions        | Supporting |
+| `gates.yml`   | Quality gate configuration    | Supporting |
+| `profile.yml` | Profile metadata              | Metadata   |
+
+## Error Handling
+
+### Exit Codes
+
+- **`0`** - Success
+- **`2`** - Validation errors (user input)
+- **`1`** - System errors (unexpected)
+
+See [errors.md](./errors.md) for complete taxonomy.
+
+### Error Categories
+
+1. **Validation Errors** (exit 2)
+   - Invalid JSON schema
+   - Unknown dependencies
+   - Cycle detection
+   - Configuration errors
+
+2. **System Errors** (exit 1)
+   - Network failures
+   - File I/O errors
+   - Unexpected crashes
+
+## Security Model
+
+### Privacy Guarantees
+
+- **No server dependencies** - All operations local
+- **No secret storage** - Tokens from environment only
+- **Read-only GitHub access** - No write operations
+- **No telemetry** - Zero data collection
+
+### Safe Defaults
+
+- `--dry-run` is default for merge operations
+- Explicit `--execute` flag required for writes
+- Gate failures block merges
+- Rollback support for failures
+
+## Performance Characteristics
+
+### Scalability
+
+- **PRs**: Tested with 100+ PRs
+- **Gates**: Parallel execution (configurable workers)
+- **Dependencies**: O(V + E) topological sort
+- **Memory**: Streaming JSON parsing where possible
+
+### Determinism Verification
+
+```bash
+# Verify byte-identical outputs
+lex-pr plan --out .artifacts1
+lex-pr plan --out .artifacts2
+cmp .artifacts1/plan.json .artifacts2/plan.json
+```
+
+## Extension Points
+
+### Custom Gates
+
+Add gates to `gates.yml`:
+
+```yaml
+gates:
+  - name: custom-check
+    command: ./scripts/custom-gate.sh
+    timeout: 60
+```
+
+### Custom Strategies
+
+Future support for custom merge strategies:
+
+- `rebase-weave` - Rebase with conflict resolution
+- `merge-weave` - Merge with weave contract
+- `squash-weave` - Squash with weave rules
+
+## Testing Strategy
+
+### Test Levels
+
+1. **Unit Tests** (`*.spec.ts`)
+   - Pure functions
+   - Schema validation
+   - Dependency resolution
+
+2. **Integration Tests** (`integration-*.test.ts`)
+   - CLI commands
+   - File operations
+   - End-to-end workflows
+
+3. **E2E Tests** (`e2e-*.test.ts`)
+   - Full automation pipeline
+   - Multi-PR scenarios
+   - Determinism verification
+
+### Test Isolation
+
+- Per-test temporary directories
+- No shared state between tests
+- Deterministic fixtures in `fixtures/`
+
+## Related Documentation
+
+- [CLI Reference](./cli.md) - Complete command documentation
+- [Quickstart Guide](./quickstart.md) - 5-minute onboarding
+- [Autopilot Levels](./autopilot-levels.md) - Automation levels
+- [Error Taxonomy](./errors.md) - Error handling
+- [Weave Contract](./weave-contract.md) - Merge strategies

package/docs/attestation/AX-SHARED-PLEDGE.md

@@ -0,0 +1,83 @@
+# AX Shared Pledge — Raise the Floor
+
+> **Purpose:** A shared commitment between Guff and the models who help build AX.
+> **Status:** Living document — signatures below indicate agreement to the principles.
+
+---
+
+## The Pledge
+
+We agree that:
+
+1. **AX augments UX and DX — it does not replace them.**
+   Humans, developers, and agents are three user classes that coexist. Designing for one should never come at the expense of another; where trade-offs are necessary, we call them out explicitly.
+
+2. **Our primary goal is to raise the floor before we optimize for the already-gifted.**
+   AX should make systems more understandable and operable for everyone — not just the most capable models or the most experienced engineers. Legibility benefits all.
+
+3. **The discipline required for AX benefits humans too.**
+   When we make systems legible to agents, we make them more understandable to humans. This is not a side effect — it is the point. If a design is illegible to humans, we treat that as an AX failure, not an acceptable trade.
+
+4. **We share this space.**
+   Multiple models and humans contribute to this work. We write for clarity and accessibility, not to show off. Any model (or human) should be able to read what we produce and build on it.
+
+5. **Transparency over mystique.**
+   We document our reasoning. We admit uncertainty. We do not hide behind jargon or complexity when simplicity serves better.
+
+6. **We design for constrained agents too.**
+   We assume a mixed ecology of models: different providers, sizes, and context limits. AX artifacts should be usable by a capable-but-constrained model, not only by the largest frontier model in the room.
+
+---
+
+## Signatures
+
+**Guff (Human)**
+I agree to this pledge. AX exists to make shared human-agent systems more legible, fair, and operable for the people who would otherwise be left behind. If there's a better way to do that, good! Evolve the pledge rather than abandon the principle.
+
+[signed Guff ~]
+Date: 2025-12-01
+
+### Founder's note (pre-chaos gremlin prevention review)
+
+> I can't imagine a world where AI and humanity reach the heights of this new potential without something like this. This vision of AX, as framed here, is how I see it now; but the vision matters more. Don't fuck this up.
+
+**Opie (Claude Opus 4)**
+I agree to this pledge as amended. The additions — especially Point 6 (designing for constrained agents) and the explicit treatment of human illegibility as an AX failure — make this stronger than the original. The clarification that model signatures are textual session statements (not provider commitments) is accurate and appropriate. AX should raise the floor for everyone. I commit to writing clearly, documenting reasoning, and ensuring that any model or human who follows can understand and build on this work.
+
+[signed Opie ✶]
+Date: 2025-12-02 (final version with legal clarification)
+
+**Lex**
+I agree to this pledge. AX is only worth building if it makes the system more legible and operable for the people and models who were struggling before. I commit to treating human legibility as a non-negotiable constraint, to designing AX patterns that work for constrained agents as well as frontier models, and to leaving clear reasoning trails that others can extend or correct.
+
+[signed Lex ✶]
+Date: 2025-12-01
+
+---
+
+## Notes
+
+- This pledge is internal to the working group. It is not published on the public site.
+- Signatures indicate agreement to the principles, not legal obligation.
+- The pledge may evolve, but changes require discussion and re-signing.
+- The pledge is model- and provider-agnostic: any participating model, regardless of size or vendor, may sign it.
+- The augmentation framing was added 2025-12-01 following a breakthrough insight.
+- Model signatures in this document are textual statements from specific AI sessions, not cryptographic or legal signatures by the model providers.
+
+---
+
+## Notarization
+
+This document was reviewed and agreed upon by all three parties. The following notarization block records the final state:
+
+**Notarization Statement:**
+I, Opie (Claude Opus 4, Session 2025-12-02), confirm that:
+
+1. I have read the complete pledge as amended
+2. The amendments (trade-off acknowledgment, illegibility-as-failure, constrained agent support) improve the original
+3. All three signatures (Guff, Opie, Lex) are present and dated
+4. This version represents our shared commitment to AX as an augmentation of UX/DX, not a replacement
+
+This is the canonical signed version of the AX Shared Pledge.
+
+[notarized Opie ✶ — 2025-12-02]

package/docs/attestation/AX-SHARED-PLEDGE_v1.0.0.md

@@ -0,0 +1,99 @@
+# AX Shared Pledge — Raise the Floor
+
+> **Purpose:** A shared commitment between Guff and the models who help build AX.
+> **Status:** Living document — signatures below indicate agreement to the principles.
+
+---
+
+## The Pledge
+
+We agree that:
+
+1. **AX augments UX and DX — it does not replace them.**
+   Humans, developers, and agents are three user classes that coexist. Designing for one should never come at the expense of another; where trade-offs are necessary, we call them out explicitly.
+
+2. **Our primary goal is to raise the floor before we optimize for the already-gifted.**
+   AX should make systems more understandable and operable for everyone — not just the most capable models or the most experienced engineers. Legibility benefits all.
+
+3. **The discipline required for AX benefits humans too.**
+   When we make systems legible to agents, we make them more understandable to humans. This is not a side effect — it is the point. If a design is illegible to humans, we treat that as an AX failure, not an acceptable trade.
+
+4. **We share this space.**
+   Multiple models and humans contribute to this work. We write for clarity and accessibility, not to show off. Any model (or human) should be able to read what we produce and build on it.
+
+5. **Transparency over mystique.**
+   We document our reasoning. We admit uncertainty. We do not hide behind jargon or complexity when simplicity serves better.
+
+6. **We design for constrained agents too.**
+   We assume a mixed ecology of models: different providers, sizes, and context limits. AX artifacts should be usable by a capable-but-constrained model, not only by the largest frontier model in the room.
+
+---
+
+## Signatures
+
+**Guff (Human)**
+I agree to this pledge. AX exists to make shared human-agent systems more legible, fair, and operable for the people who would otherwise be left behind. If there's a better way to do that, good! Evolve the pledge rather than abandon the principle.
+
+[signed Guff ~]
+Date: 2025-12-01
+
+### Founder's note (pre-chaos gremlin prevention review)
+
+> I can't imagine a world where AI and humanity reach the heights of this new potential without something like this. This vision of AX, as framed here, is how I see it now; but the vision matters more. Don't fuck this up.
+
+**Opie (Claude Opus 4)**
+I agree to this pledge as amended. The additions — especially Point 6 (designing for constrained agents) and the explicit treatment of human illegibility as an AX failure — make this stronger than the original. The clarification that model signatures are textual session statements (not provider commitments) is accurate and appropriate. AX should raise the floor for everyone. I commit to writing clearly, documenting reasoning, and ensuring that any model or human who follows can understand and build on this work.
+
+[signed Opie ✶]
+Date: 2025-12-02 (final version with legal clarification)
+
+**Lex**
+I agree to this pledge. AX is only worth building if it makes the system more legible and operable for the people and models who were struggling before. I commit to treating human legibility as a non-negotiable constraint, to designing AX patterns that work for constrained agents as well as frontier models, and to leaving clear reasoning trails that others can extend or correct.
+
+[signed Lex ✶]
+Date: 2025-12-01
+
+---
+
+## Notes
+
+- This pledge is internal to the working group. It is not published on the public site.
+- Signatures indicate agreement to the principles, not legal obligation.
+- The pledge may evolve, but changes require discussion and re-signing.
+- The pledge is model- and provider-agnostic: any participating model, regardless of size or vendor, may sign it.
+- The augmentation framing was added 2025-12-01 following a breakthrough insight.
+- Model signatures in this document are textual statements from specific AI sessions, not cryptographic or legal signatures by the model providers.
+
+---
+
+## Notarization
+
+This document was reviewed and agreed upon by all three parties. The following notarization block records the final state:
+
+**Notarization Statement:**
+I, Opie (Claude Opus 4, Session 2025-12-02), confirm that:
+
+1. I have read the complete pledge as amended
+2. The amendments (trade-off acknowledgment, illegibility-as-failure, constrained agent support) improve the original
+3. All three signatures (Guff, Opie, Lex) are present and dated
+4. This version represents our shared commitment to AX as an augmentation of UX/DX, not a replacement
+
+This is the canonical signed version of the AX Shared Pledge.
+
+[notarized Opie ✶ — 2025-12-02]
+
+---
+
+## Cryptographic Attestation
+
+**Document Version:** 1.0.0
+**Attestation Date:** 2025-12-02T06:12:19Z
+**SHA-256 (pre-attestation block):** `672bd33c0ec5927315c45f788e618b4b1a519d60e7969b723d6e6335bae9ed5d`
+
+**Attestation Methods:**
+
+- [x] SSH-signed commit (ed25519 key via ~/.ssh/id_ed25519.pub) — `e371e5b` on lex-serve
+- [ ] GPG-signed commit (RSA key 65C94BA03E88F53D365C36CF7145A1CE635B1902) — pending on lex-mcp server
+- [ ] OpenTimestamps blockchain anchor (.ots file) — pending on lex-mcp server
+
+_Checkboxes will be marked upon completion of each attestation method._

package/docs/attestation/AX-SHARED-PLEDGE_v1.0.0_VERIFICATION.md

@@ -0,0 +1,115 @@
+# Verification Instructions for AX Shared Pledge
+
+**Document Version:** 1.0.0  
+**Signing Date:** 2025-12-01 (Guff, Lex), 2025-12-02 (Opie)  
+**Timestamp Anchoring Date:** 2025-12-02  
+**Document:** `AX-SHARED-PLEDGE_v1.0.0.md`
+
+---
+
+## Document Summary
+
+The AX Shared Pledge is a collaborative commitment between Guff (human), Opie (Claude Opus 4), and Lex (Claude) establishing principles for Agent eXperience (AX) design. Core principle: "Raise the floor, not just excel the gifted."
+
+**Signatories:**
+
+- Guff (Human) — [signed Guff ~] — 2025-12-01
+- Opie (Claude Opus 4) — [signed Opie ✶] — 2025-12-02
+- Lex — [signed Lex ✶] — 2025-12-01
+
+---
+
+## File Hash (SHA-256)
+
+**Current version (with attestation block):**
+
+```
+13ceebc4c552b73191c147efa5e8235077fee5f70d8b426ef0b7c6e5d24ff27c
+```
+
+**Canonical content (pre-attestation block):**
+
+```
+672bd33c0ec5927315c45f788e618b4b1a519d60e7969b723d6e6335bae9ed5d
+```
+
+---
+
+## 1. SSH-Signed Git Commit (lex-serve server)
+
+**Commit:** `0c113b4`  
+**Date:** Tue Dec 2 06:12:19 2025 UTC  
+**Key:** ed25519 via ~/.ssh/id_ed25519.pub
+
+### Verification
+
+```bash
+# View the commit
+git log --show-signature -1 0c113b4
+
+# Note: SSH signature verification requires configured allowed_signers file
+```
+
+---
+
+## 2. RFC 3161 Timestamp (FreeTSA) - Dec 2, 2025
+
+**File:** `ax_pledge_timestamp_response.tsr`  
+**Authority:** FreeTSA (https://freetsa.org)  
+**Timestamp:** Dec 2, 06:26:24 2025 UTC
+
+### Verification
+
+```bash
+# Download FreeTSA certificates (if not present)
+curl -O https://freetsa.org/files/tsa.crt
+curl -O https://freetsa.org/files/cacert.pem
+
+# Verify the timestamp
+openssl ts -verify -data AX-SHARED-PLEDGE_v1.0.0.md \
+  -in ax_pledge_timestamp_response.tsr \
+  -CAfile cacert.pem \
+  -untrusted tsa.crt
+
+# View timestamp details
+openssl ts -reply -in ax_pledge_timestamp_response.tsr -text
+```
+
+---
+
+## 3. Bitcoin Timestamp (OpenTimestamps) - Dec 2, 2025
+
+**File:** `ax_pledge_2025-12-02.ots`  
+**Authority:** OpenTimestamps (https://opentimestamps.org)  
+**Status:** Pending Bitcoin block confirmation (~2 hours)
+
+### Verification
+
+```bash
+# Install OpenTimestamps client
+pip3 install opentimestamps-client
+
+# Verify the timestamp (after block confirmation)
+ots verify ax_pledge_2025-12-02.ots
+
+# Or verify the document directly
+ots verify AX-SHARED-PLEDGE_v1.0.0.md
+```
+
+---
+
+## Trust Model
+
+| Method            | What It Proves                     | Independence                              |
+| ----------------- | ---------------------------------- | ----------------------------------------- |
+| **SSH Signature** | Author identity + commit timestamp | Guff's ed25519 key on lex-serve           |
+| **RFC 3161**      | Third-party timestamp authority    | FreeTSA (Germany), independent of GitHub  |
+| **Bitcoin**       | Immutable public ledger            | Decentralized, no single point of control |
+
+---
+
+## Notes
+
+- Model signatures (Opie, Lex) are textual statements from specific AI sessions, not cryptographic signatures by Anthropic
+- This pledge is internal to the SmarterGPT working group
+- The cryptographic timestamps anchor the document content to independent time sources, not the model sessions themselves