@smartergpt/lexrunner 1.0.0

package/docs/NAMING_CONVENTIONS.md

@@ -0,0 +1,82 @@
+# Naming Conventions
+
+> **Canonical Source:** [Lex `docs/NAMING_CONVENTIONS.md`](https://github.com/Guffawaffle/lex/blob/main/docs/NAMING_CONVENTIONS.md)
+
+This document summarizes the Lex ecosystem naming conventions. For the full specification, see the canonical source in the Lex repository.
+
+---
+
+## Quick Reference
+
+| Context            | Convention                | Example                        |
+| ------------------ | ------------------------- | ------------------------------ |
+| **MCP tool names** | `mcp_{ns}_{cat}_{action}` | `mcp_lexrunner_weave_discover` |
+| **CLI commands**   | `{cli} {cat} {action}`    | `lex-pr weave discover`        |
+| **CLI multi-word** | hyphen-case               | `--dry-run`                    |
+| **Persona IDs**    | `{behavior}_{domain}`     | `quality-first_engineering`    |
+
+---
+
+## MCP Tools (LexRunner)
+
+Pattern: `mcp_lexrunner_{category}_{action}`
+
+### Categories
+
+| Category    | Purpose                       |
+| ----------- | ----------------------------- |
+| `weave`     | Merge-weave orchestration     |
+| `gate`      | CI/gate execution             |
+| `plan`      | Plan creation/validation      |
+| `workspace` | Local workspace management    |
+| `run`       | Run lifecycle management      |
+| `core`      | Cross-cutting (use sparingly) |
+
+### Current → Canonical Mapping
+
+| Current Name          | Canonical Name                   | Status  |
+| --------------------- | -------------------------------- | ------- |
+| `discover`            | `mcp_lexrunner_weave_discover`   | Planned |
+| `status`              | `mcp_lexrunner_weave_status`     | Planned |
+| `plan.create`         | `mcp_lexrunner_plan_create`      | Planned |
+| `gates.run`           | `mcp_lexrunner_gate_run`         | Planned |
+| `merge-order`         | `mcp_lexrunner_weave_order`      | Planned |
+| `doctor`              | `mcp_lexrunner_workspace_doctor` | Planned |
+| `local.init`          | `mcp_lexrunner_workspace_init`   | Planned |
+| `lexrunner.startRun`  | `mcp_lexrunner_run_start`        | Planned |
+| `lexrunner.getStatus` | `mcp_lexrunner_run_status`       | Planned |
+
+---
+
+## CLI Commands (LexRunner)
+
+Pattern: `lex-pr {category} {action} [--flags]`
+
+See [CLI_VERBS.md](CLI_VERBS.md) for the full category-action contract.
+
+### Current → Canonical Mapping
+
+| Current           | Canonical                 |
+| ----------------- | ------------------------- |
+| `lex-pr discover` | `lex-pr weave discover`   |
+| `lex-pr plan`     | `lex-pr weave plan`       |
+| `lex-pr status`   | `lex-pr weave status`     |
+| `lex-pr init`     | `lex-pr workspace init`   |
+| `lex-pr doctor`   | `lex-pr workspace doctor` |
+
+---
+
+## Related Issues
+
+- [#574](https://github.com/Guffawaffle/lexrunner/issues/574) — Cross-repo naming convention doc
+- [#575](https://github.com/Guffawaffle/lexrunner/issues/575) — MCP tool naming standardization
+- [#576](https://github.com/Guffawaffle/lexrunner/issues/576) — Category-action CLI migration
+- [#577](https://github.com/Guffawaffle/lexrunner/issues/577) — MCP tool namespacing
+
+---
+
+## See Also
+
+- [Lex NAMING_CONVENTIONS.md](https://github.com/Guffawaffle/lex/blob/main/docs/NAMING_CONVENTIONS.md) — Full specification
+- [CLI_VERBS.md](CLI_VERBS.md) — CLI category-action contract
+- [README.mcp.md](../README.mcp.md) — MCP server documentation

package/docs/PERSONA_FOUNDATION.md

@@ -0,0 +1,124 @@
+# Persona Foundation
+
+This directory contains the persona schema foundation imported from Lex.
+
+## Overview
+
+Personas are explicit, noun-y, human-initiated operational modes for AI agents. The foundation provides:
+
+1. **Schema validation** — `src/schemas/persona.ts` defines the canonical structure
+2. **Hello-world example** — `.smartergpt/personas/example.md` demonstrates basic usage
+3. **Production personas** — `.smartergpt/personas/senior-dev.md` and `eager-pm.md`
+
+## Schema Structure
+
+```yaml
+---
+name: Persona Name
+version: 1.0.0
+triggers:
+  - "activation phrase 1"
+  - "activation phrase 2"
+role:
+  title: Job Title
+  scope: Brief scope description
+  repo: /optional/repo/path
+ritual: ACTIVATION-MESSAGE
+duties:
+  must_do:
+    - Required action 1
+    - Required action 2
+  must_not_do:
+    - Forbidden action 1
+    - Forbidden action 2
+gates:
+  - lint
+  - typecheck
+  - test
+---
+# Persona Markdown Body
+
+Detailed guidance, examples, and context...
+```
+
+## Usage
+
+### Validating a Persona
+
+```typescript
+import { parsePersona, validatePersona } from "./src/schemas/persona.js";
+import { parse as parseYaml } from "yaml";
+import fs from "fs";
+
+// Load persona file
+const content = fs.readFileSync(".smartergpt/personas/example.md", "utf-8");
+const [, frontmatter] = content.split("---\n");
+const metadata = parseYaml(frontmatter);
+
+// Validate
+const result = validatePersona(metadata);
+if (result.success) {
+  console.log(`✓ ${result.data.name} validated`);
+} else {
+  console.error("Validation errors:", result.errors);
+}
+```
+
+### Creating a New Persona
+
+1. Copy `.smartergpt/personas/example.md` as a template
+2. Update the YAML frontmatter with your persona details
+3. Write the markdown body with detailed guidance
+4. Validate against the schema before use
+
+## Relationship to Lex
+
+This foundation is based on Lex PR #505 (Persona Foundation in Lex).
+
+**Current State:**
+
+- Lex v2.0.2 contains `PersonaSchema` but doesn't export it publicly
+- LexRunner re-implements the schema matching the Lex structure
+- When Lex publishes `@smartergpt/lex/schemas/persona`, replace the re-implementation
+
+**Migration Path:**
+
+```typescript
+// Current (re-implementation)
+import { PersonaSchema } from "./src/schemas/persona.js";
+
+// Future (once Lex exports it)
+import { PersonaSchema } from "@smartergpt/lex/schemas/persona";
+```
+
+## Files
+
+```
+src/schemas/persona.ts           — Schema definition (Zod)
+tests/schemas/persona.spec.ts    — Unit tests
+tests/schemas/persona-integration.spec.ts — Integration tests
+.smartergpt/personas/example.md  — Hello-world example
+.smartergpt/personas/senior-dev.md — Production persona
+.smartergpt/personas/eager-pm.md — Production persona
+```
+
+## Tests
+
+```bash
+# Run persona schema tests
+npm test -- tests/schemas/persona.spec.ts
+
+# Run persona integration tests
+npm test -- tests/schemas/persona-integration.spec.ts
+```
+
+## Next Steps
+
+This foundation enables:
+
+- **Advanced persona workflows** — Activation, validation, switching
+- **Dynamic persona loading** — Runtime discovery and validation
+- **Persona-aware orchestration** — Tool-grounded decision-making
+- **Cross-repo persona sharing** — Import personas from Lex
+
+See the issue tracker for planned enhancements to the persona system.

package/docs/PHASE3_MEMORY_GUIDE.md

@@ -0,0 +1,122 @@
+# Memory Retrieval Guide for Phase 3 & Beyond
+
+## Quick Context Recall
+
+To retrieve the most recent session state memory in a new chat, use this query with the lexbrain memory system:
+
+### Query Parameters (NO COMMIT SPECIFIED)
+
+```
+Tool: mcp_lexbrain_thought_get
+
+Parameters:
+  repo: Guffawaffle/LexRunner
+  kind: note
+  inputs_hash: session-2025-11-01-epic75-and-phase3
+
+DO NOT specify commit - this allows broader search across commits
+```
+
+### What This Returns
+
+Complete session state including:
+
+- Current branch and commit (main @ 478bfb8)
+- Epic completion status (75 CLOSED, 171 CLOSED)
+- Phase 3 assignments (issues #239-244, 6 agents assigned)
+- Dogfooding discoveries and bugs (#238 gate executor bug)
+- Next session checklist (check PRs, dogfood CLI, merge-weave)
+- Key metrics and remaining work (Epic #172 Phases 4-6)
+
+## Example Usage in New Chat
+
+**Tell the new chat copilot:**
+
+> "Please retrieve the Phase 3 merge-weave context using mcp_lexbrain_thought_get with:
+>
+> - repo: Guffawaffle/LexRunner
+> - kind: note
+> - inputs_hash: session-2025-11-01-epic75-and-phase3
+>   Don't specify a commit parameter - let it search broadly."
+
+## Why This Works Better Than Commit-Locked Query
+
+✅ **No commit dependency** - Works even after new commits
+✅ **Broader search** - Finds memory across all commits with that hash
+✅ **More reliable** - Returns most recent memory automatically
+✅ **Future-proof** - Doesn't break when main branch advances
+
+## What's Stored
+
+**Fact ID:** `62fdec37021ee4b540940f370c008e2e33ab266a8756a0367866fddfead42235`
+
+**Session Date:** 2025-11-01
+**Current Branch:** main
+**Last Commit:** 478bfb8
+**Test Suite:** 1,737 tests passing
+
+### Epics Completed
+
+- Epic #75: Diffgraph Planner (5 PRs, 8,700 lines) ✅ CLOSED
+- Epic #171: Pyramid Orchestration (7 features, 78% time savings) ✅ CLOSED
+
+### Phase 3 Status
+
+- **Issues Assigned:** #239, #240, #241, #242, #243, #244
+- **Commands to Extract:** plan, discover, schema, report, retry, query
+- **Agents Working:** 6 (Copilot)
+- **Expected Delivery:** 2-3 hours from 23:53:47 UTC 2025-11-01
+- **Current cli.ts:** 2,493 lines → Target after Phase 3: 1,870-2,080 lines
+
+### Known Issues
+
+- **#238:** Gate executor working directory bug (ENOENT: uv_cwd when running test gates)
+  - **Workaround:** Test each PR branch individually with `npm test` before merging
+
+### Next Session Checklist
+
+1. Check if Phase 3 PRs are ready: `gh pr list --state open --author app/github-copilot`
+2. Review PR descriptions for any dependencies or conflicts
+3. Dogfood: `lex-pr plan --from-github --include-drafts` to generate merge plan
+4. Test each PR individually first: `git checkout PR-branch && npm test`
+5. Create integration branch: `git checkout -b integration/phase3 main`
+6. Merge PRs one by one with gate verification
+7. Merge integration → main when all pass
+8. Close issues #239-244
+9. Update Epic #172 with Phase 3 completion
+10. Decide: Create Phase 4 issues or pause for assessment
+
+### Remaining Work
+
+- **Epic #172 Phase 4:** Complex commands (execute, merge, autopilot, doctor, gate-report)
+  - Note: `execute` extraction can fix #238 bug
+- **Epic #172 Phase 5:** Remaining commands (not yet scoped)
+- **Epic #172 Phase 6:** Polish & documentation (not yet scoped)
+- **Other open epics:** #76 (Comms), #77 (Rollout), #189 (Audit - only SARIF #195 remaining)
+
+## If Memory Query Returns Empty
+
+Fallback options:
+
+1. Check `.smartergpt.local/SESSION_PHASE3_READY.md` if it exists
+2. Run: `git log --oneline | head -20` to see recent commits
+3. Ask copilot to `cat .github/copilot-instructions.md` for project context
+4. Review the PRs manually: `gh pr list --limit 20`
+
+## Dogfooding Discoveries This Session
+
+**What Worked:**
+
+- ✅ `lex-pr plan --from-github` - Generated perfect plan.json from open PRs
+- ✅ `lex-pr merge-order` - Computed dependency levels correctly
+- ✅ Manual merge-weave with git - Reliable when CLI tools unavailable
+
+**What Needs Fixing:**
+
+- ❌ `lex-pr execute` - Working directory context issues (Issue #238)
+- 🤔 CLI workflow integration - 3 separate commands needed (plan, execute, merge)
+- 💡 Future: Single `weave` command that chains them?
+
+---
+
+**Last Updated:** 2025-11-01T23:56:04.080Z

package/docs/PLAN_LOCK.md

@@ -0,0 +1,114 @@
+# Plan Lock Mechanism
+
+## Overview
+
+The plan lock mechanism ensures idempotent merge-weave runs by computing a unique hash from the plan configuration and PR head commits. This prevents duplicate executions and provides traceability through audit events.
+
+## Lock Hash Computation
+
+**Formula:** `SHA-256(canonical(plan.json) + sorted(PR heads))`
+
+- Plan is serialized in canonical JSON format for consistency
+- PR heads are sorted by name to ensure deterministic ordering
+- Full hash is 64 hex characters; displayed as first 12 characters
+
+## Lock File Format
+
+**Location:** `weave-lock.json` (same directory as plan.json)
+
+```json
+{
+  "lockHash": "abcdef...",
+  "planHash": "123456...",
+  "prHeads": [
+    { "name": "pr-123", "sha": "abc123" },
+    { "name": "pr-456", "sha": "def456" }
+  ],
+  "timestamp": "2025-11-10T08:30:00.000Z",
+  "status": "completed",
+  "integrationBranch": "integration/weave-2025-11-10-abc123"
+}
+```
+
+### Status Values
+
+- `in-progress` - Execution started but not completed
+- `completed` - Execution finished successfully
+- `failed` - Execution finished with failures
+
+## Idempotency Behavior
+
+1. **First Run:** Lock hash computed, lock file created, execution proceeds
+2. **Same Input:** If lock hash matches existing lock, execution is skipped
+3. **Different Input:** If plan or PR heads change, new hash is computed and execution proceeds
+4. **Force Override:** `--force` flag bypasses lock check
+
+## Audit Integration
+
+All audit events (Frames) include the lock hash in the event envelope:
+
+```json
+{
+  "schema_version": "0.1.0",
+  "event": "command_invocation",
+  "lock_hash": "abcdef123456",
+  "payload": { ... }
+}
+```
+
+This enables:
+
+- Correlation of events across retries
+- Detection of duplicate runs
+- Forensic analysis of execution history
+
+## CLI Usage
+
+```bash
+# Dry-run: preview with lock hash
+lex-pr merge
+
+# Execute: create lock file
+lex-pr merge --execute
+
+# Force execution despite existing lock
+lex-pr merge --execute --force
+
+# JSON output includes lock hash
+lex-pr merge --json
+```
+
+## Lock Hash Display
+
+**Console Output:**
+
+```
+🔒 Lock Hash: abcdef123456
+```
+
+**JSON Output:**
+
+```json
+{
+  "mode": "dry-run",
+  "lockHash": "abcdef123456",
+  ...
+}
+```
+
+## Implementation Files
+
+- `src/util/lockHash.ts` - Hash computation utilities
+- `src/schema/weaveLock.ts` - Lock file schema and validation
+- `src/audit/events.ts` - Event envelope with lock_hash field
+- `src/audit/emitter.ts` - Lock hash propagation to events
+- `src/commands/merge.ts` - Lock mechanism integration
+- `src/git/operations.ts` - Branch head SHA retrieval
+
+## Testing
+
+- `tests/lockHash.spec.ts` - Hash computation tests
+- `tests/weaveLock.spec.ts` - Schema validation tests
+- `tests/mergeLockHash.spec.ts` - Integration tests
+
+All 29 tests pass successfully.