@smartergpt/lexrunner 1.0.0

package/docs/EXE-012-investigation-summary.md

@@ -0,0 +1,300 @@
+# EXE-012 Investigation Summary: Executor Registry Status
+
+**Date:** 2025-12-25  
+**Investigator:** GitHub Copilot Agent  
+**Issue:** EXE-012 - Investigate #412 Executor Registry status
+
+## Executive Summary
+
+**Finding:** Issue #412 is **NOT** about an "Executor Registry". It's titled "LPR-048: Lex Memory Integration" and concerns integrating Lex memory APIs into LexRunner workflows.
+
+**Impact on PR #583:** The dependency listing "Depends-on: #412 (Executor Registry)" in PR #583 is **incorrect**. However, this does not block PR #583, which was already merged on 2025-12-17.
+
+**Registry Status:** A production ExecutorRegistry does not exist in `src/`. Only a test fixture exists in `tests/fixtures/executors/registry.ts`.
+
+---
+
+## Investigation Process
+
+### 1. GitHub Issue/PR Lookup
+
+**Issue #412 Details:**
+
+- **Title:** "LPR-048: Lex Memory Integration"
+- **State:** Closed (2025-12-16)
+- **Purpose:** Integrate Lex's memory APIs (`lex recall`, `lex remember`, `lex timeline`)
+- **Scope:** Creating `src/integrations/lex-memory.ts` and related MCP tools
+- **Conclusion:** This is about memory integration, NOT an executor registry
+
+**PR #412:** Does not exist (404 Not Found)
+
+**PR #583 Details:**
+
+- **Title:** "Add executor manifest validation to CI pipeline"
+- **State:** Merged (2025-12-17)
+- **Dependency Listed:** "Depends-on: #412 (Executor Registry)" ❌ INCORRECT
+- **Actual Dependencies:**
+  - #405 (ExecutorManifestSchema) ✅ Implemented
+  - Validation logic itself ✅ Implemented
+
+### 2. Codebase Search for Registry
+
+**Search Results:**
+
+```bash
+# Files mentioning "registry" (case-insensitive)
+tests/fixtures/executors/registry.ts     # Test fixture only
+tests/fixtures/executors/index.ts        # Re-exports registry
+tests/executors/lifecycle.spec.ts        # Uses test registry
+tests/executors/guardrailEnforcement.spec.ts  # Uses test registry
+```
+
+**No production registry found in `src/`**
+
+### 3. Test Fixture Analysis
+
+**Location:** `tests/fixtures/executors/registry.ts`
+
+**Comment in test fixture (previous, now corrected):**
+
+```typescript
+/**
+ * Placeholder ExecutorRegistry for Testing
+ *
+ * This is a simplified mock implementation until PR #412 is merged.
+ * Real implementation will provide full registry functionality.
+ */
+```
+
+**Analysis:** This comment was misleading and has been corrected. It references "PR #412" which doesn't exist and conflates issue #412 (Lex Memory) with a registry implementation.
+
+**Functionality:**
+
+- `register(executor)` - Add executor to in-memory map
+- `load(executorId)` - Retrieve executor by ID
+- `list()` - List registered executor IDs
+- `clear()` - Clear registry (for tests)
+
+### 4. Executor Architecture Components
+
+**What EXISTS:**
+
+1. **ExecutorManifestSchema** (`src/schemas/executorManifest.ts`)
+   - Zod schema for `executor-manifest.yaml`
+   - Defines tool budget, guardrails, Jordan-mode protocol
+   - Implemented via issue #405
+
+2. **Manifest Validation** (`scripts/validate-manifests.ts`)
+   - CI validation script
+   - Validates all manifests against schema
+   - Implemented via PR #583
+
+3. **Senior Dev Executor** (`executors/senior-dev/`)
+   - Full manifest following executor-1.0.0 schema
+   - TypeScript implementation in `src/executors/seniorDev/`
+   - Migrated via issue #415
+
+4. **Test Fixtures** (`tests/fixtures/executors/`)
+   - Mock registry for testing
+   - Mock executor implementations
+   - Used in lifecycle and guardrail tests
+
+**What DOES NOT EXIST:**
+
+1. **Production ExecutorRegistry** in `src/executors/registry.ts`
+2. **Dynamic executor loading** from manifest files
+3. **Executor discovery system**
+
+---
+
+## Findings by Acceptance Criteria
+
+### ✅ Locate #412 issue and check status
+
+**Status:** Closed (2025-12-16)  
+**Title:** LPR-048: Lex Memory Integration  
+**Type:** Issue (not PR)  
+**Scope:** Memory API integration, NOT executor registry
+
+### ✅ If merged: identify which files contain registry implementation
+
+**Not applicable** - #412 was about Lex Memory, not a registry.
+
+**Registry-related files:**
+
+- `tests/fixtures/executors/registry.ts` - Test fixture only (not production code)
+- `src/schemas/executorManifest.ts` - Schema for manifests (not a registry)
+- `scripts/validate-manifests.ts` - Validation script (not a registry)
+
+### ✅ If merged: update PR #583 description
+
+**Not applicable** - PR #583 was already merged.
+
+**Recommendation:** Create a follow-up issue to clarify the dependency confusion and update any references to "#412 (Executor Registry)" in documentation or code comments.
+
+### ✅ If not merged: determine if registry is needed
+
+**Analysis:**
+
+**Current approach:** Direct TypeScript imports
+
+```typescript
+import { executeReview } from "../executors/seniorDev/core.js";
+```
+
+**Registry pattern would enable:**
+
+- Dynamic executor discovery
+- Runtime manifest loading
+- Plugin-style executor additions
+- Executor lifecycle management
+
+**Recommendation:**
+
+- **For now:** Test fixture registry is sufficient
+- **For future:** If dynamic executor loading is needed, create a new issue specifically for implementing a production registry in `src/executors/registry.ts`
+- **Priority:** Low - current direct import approach works fine for a small number of executors
+
+### ✅ Document registry location in `docs/architecture/executors.md`
+
+**Created:** `docs/architecture/executors.md`
+
+**Contents:**
+
+- Executor architecture overview
+- Manifest schema documentation
+- Registry status (test fixture vs production)
+- File structure
+- Related issues clarification
+- Implementation notes and recommendations
+
+---
+
+## Related Issues Analysis
+
+### Completed Issues
+
+**#404 - Executor Canonicalization**
+
+- Defined canonical structure for executors
+- Established `executors/` vs `project/` separation
+- Status: Closed (2025-12-01)
+
+**#405 - ExecutorManifestSchema**
+
+- Implemented Zod schema for manifests
+- Created `src/schemas/executorManifest.ts`
+- Status: Closed (2025-11-26)
+
+**#415 - Senior Dev Migration**
+
+- Migrated Senior Dev executor to canonical location
+- Demonstrates full manifest implementation
+- Status: Closed (2025-12-17)
+
+**#583 - Manifest Validation CI**
+
+- Created validation script
+- Added CI pipeline integration
+- Status: Merged (2025-12-17)
+
+### Dependency Confusion
+
+**Issue #415** lists:
+
+```
+Dependencies:
+- Depends-on: #412 (EXE-006: Executor Registry & Loader)
+- Depends-on: #413 (EXE-009: Manifest Validation in CI)
+```
+
+**Issue #412** is actually "LPR-048: Lex Memory Integration"
+
+**Hypothesis:** There may have been a planned issue for "EXE-006: Executor Registry & Loader" that was never created, and #412 was mistakenly referenced instead.
+
+---
+
+## Recommendations
+
+### Immediate Actions
+
+1. ✅ **Document current state** - COMPLETED
+   - Created `docs/architecture/executors.md`
+   - Clarified registry status
+   - Documented file locations
+
+2. **Update code comment** - ✅ COMPLETED
+   - File: `tests/fixtures/executors/registry.ts`
+   - Updated to clarify this is a test fixture
+   - Clarified that production registry is not currently planned
+   - Noted that direct imports are the current approach
+
+3. **Create clarification issue** - OPTIONAL
+   - Title: "Clarify executor registry dependency confusion"
+   - Scope: Document the #412 confusion and clean up references
+
+### Future Considerations
+
+**If dynamic executor loading becomes a requirement:**
+
+1. Create new issue: "EXE-XXX: Implement Production Executor Registry"
+2. Scope:
+   - Create `src/executors/registry.ts`
+   - Implement manifest loading from `executors/` directory
+   - Support runtime executor discovery
+   - Executor lifecycle management
+3. Priority: **Not currently planned** - current direct import approach is intentional
+
+**Why current approach is preferred:**
+
+- Small number of executors (currently only senior-dev)
+- Executors are TypeScript modules with compile-time type safety
+- Test fixtures provide registry pattern for testing
+- CI validation ensures manifest correctness
+- No runtime discovery requirement
+
+---
+
+## Conclusion
+
+**PR #583 dependency on "#412 (Executor Registry)" was incorrect**, but this does not impact PR #583's completion status. The PR successfully implemented manifest validation, which was its actual goal.
+
+**A production executor registry does not exist**, only a test fixture. This is acceptable for the current architecture, which uses direct imports for executor loading.
+
+**Documentation has been created** at `docs/architecture/executors.md` to clarify the executor architecture and registry status.
+
+**No blocking issues identified** for the executor canonicalization epic (#404).
+
+---
+
+## Appendix: File Inventory
+
+### Executor Manifest & Schema
+
+- `src/schemas/executorManifest.ts` - Zod schema ✅
+- `executors/senior-dev/executor-manifest.yaml` - Example manifest ✅
+- `scripts/validate-manifests.ts` - Validation script ✅
+- `scripts/generate-executor-manifest-schema.ts` - JSON Schema generator ✅
+
+### Executor Implementation
+
+- `src/executors/seniorDev/core.ts` - Core logic ✅
+- `src/executors/seniorDev/types.ts` - Type definitions ✅
+- `src/executors/seniorDev/index.ts` - Public exports ✅
+
+### Test Fixtures
+
+- `tests/fixtures/executors/registry.ts` - Test registry ✅
+- `tests/fixtures/executors/mock-executor.ts` - Mock executor ✅
+- `tests/fixtures/executors/types.ts` - Test types ✅
+- `tests/fixtures/executors/index.ts` - Fixture exports ✅
+
+### Documentation
+
+- `docs/executor-authoring.md` - Authoring guide ✅
+- `docs/executor-decoupling.md` - Architecture patterns ✅
+- `docs/architecture/executors.md` - Architecture reference ✅ NEW
+
+### Production Registry
+
+- `src/executors/registry.ts` - ❌ DOES NOT EXIST

package/docs/GATE_ATTESTATION_GUIDE.md

@@ -0,0 +1,237 @@
+# Gate Attestation & Import Guide
+
+## Overview
+
+When gates are run manually (e.g., `npm run build && npm test`) outside of lexrunner, the results aren't automatically captured by the gate tracking system. This causes `merge_apply` to show 0 eligible PRs, even though the gates actually passed.
+
+This guide explains how to use the new **gate attestation** and **import** commands to record gate results from external runs.
+
+## Problem Statement
+
+During merge-weave execution, you might:
+
+1. Run gates manually in each repo (`npm run build && npm test`)
+2. Fix test failures, commit, and push
+3. Run `merge_apply --dry-run`
+4. Get "0 items eligible to merge" even though everything passed
+
+This happens because lexrunner's gate tracking system only sees results from `gates_run`, not manual terminal commands.
+
+## Solution: Gate Attestation & Import
+
+### Option 1: Gate Attestation (Recommended for Manual Runs)
+
+Use `gate attest` to manually attest that gates have passed:
+
+```bash
+lex-pr gate attest \
+  --item "pr-650" \
+  --gates "build,test" \
+  --reason "Verified manually - npm run build && npm test passed"
+```
+
+**Output:**
+
+```
+✅ Attested 2 gate(s) for item 'pr-650'
+   Status: pass
+   Reason: Verified manually - npm run build && npm test passed
+   Files created:
+     - .smartergpt/gate-results/pr-650-build.json
+     - .smartergpt/gate-results/pr-650-test.json
+
+💡 These gate results are now available for merge eligibility evaluation.
+```
+
+**Options:**
+
+- `--item <name>`: Item name (e.g., PR number or branch name) - **Required**
+- `--gates <names>`: Comma-separated list of gate names - **Required**
+- `--reason <reason>`: Reason for attestation (for audit trail) - **Required**
+- `--status <status>`: Gate status (`pass` or `fail`) - Default: `pass`
+- `--out-dir <dir>`: Output directory - Default: `.smartergpt/gate-results`
+- `--duration <ms>`: Duration in milliseconds - Default: `0`
+
+### Option 2: Gate Import (For CI or External Systems)
+
+Use `gate import` to import results from external sources:
+
+```bash
+lex-pr gate import \
+  --item "pr-651" \
+  --gate "build" \
+  --status "pass" \
+  --duration 5000 \
+  --meta '{"ci_build_id":"12345","commit_sha":"abc123"}'
+```
+
+**Output:**
+
+```
+✅ Imported gate result for 'pr-651' - 'build'
+   Status: pass
+   Duration: 5000ms
+   Output: .smartergpt/gate-results/pr-651-build.json
+
+💡 This gate result is now available for merge eligibility evaluation.
+```
+
+**Options:**
+
+- `--item <name>`: Item name - **Required**
+- `--gate <name>`: Gate name - **Required**
+- `--status <status>`: Gate status (`pass` or `fail`) - **Required**
+- `--input <file>`: Input file to import (gate result JSON)
+- `--duration <ms>`: Duration in milliseconds - Default: `0`
+- `--out-dir <dir>`: Output directory - Default: `.smartergpt/gate-results`
+- `--log <file>`: Path to log file to attach
+- `--meta <json>`: Additional metadata as JSON string
+
+## Gate Result Format
+
+Gate results are stored as JSON files following the `GateReport` schema:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "item": "pr-650",
+  "gate": "build",
+  "status": "pass",
+  "duration_ms": 0,
+  "started_at": "2026-01-02T08:00:00.000Z",
+  "meta": {
+    "attestation": "manual",
+    "reason": "Verified manually - npm run build && npm test passed",
+    "attested_by": "developer",
+    "attested_at": "2026-01-02T08:00:00.000Z"
+  }
+}
+```
+
+## Integration with Merge Eligibility
+
+### How It Works
+
+1. **Create/Attest Gate Results**: Use `gate attest` or `gate import` to create gate result files
+2. **Results are Stored**: Files are saved to `.smartergpt/gate-results/` (or custom directory)
+3. **Merge Evaluation**: When `merge_apply` runs, it automatically loads gate results from the directory
+4. **Eligibility Determined**: Items with passing required gates become eligible for merge
+
+### Example Workflow
+
+```bash
+# 1. Run gates manually in each repo
+cd repo-pr-650
+npm run build && npm test
+
+# 2. Attest the results
+lex-pr gate attest \
+  --item "pr-650" \
+  --gates "build,test" \
+  --reason "Verified manually - all tests passed"
+
+# 3. Repeat for other PRs
+cd ../repo-pr-651
+npm run lint
+lex-pr gate attest \
+  --item "pr-651" \
+  --gates "lint" \
+  --reason "Linter passed"
+
+# 4. Check merge eligibility
+lex-pr weave merge-order  # Shows items eligible for merge
+
+# 5. Apply merge (dry run first)
+lex-pr merge --dry-run
+```
+
+## Advanced Usage
+
+### Importing from CI
+
+If you have CI results in a standardized format:
+
+```bash
+# Import from GitHub Actions or similar
+lex-pr gate import \
+  --item "pr-650" \
+  --gate "ci-build" \
+  --status "pass" \
+  --duration 120000 \
+  --meta '{"ci_system":"github-actions","run_id":"123456","workflow":"CI"}' \
+  --log build.log
+```
+
+### Batch Attestation
+
+For multiple PRs:
+
+```bash
+# Create a script to attest all PRs
+for pr in 650 651 652; do
+  lex-pr gate attest \
+    --item "pr-$pr" \
+    --gates "build,test,lint" \
+    --reason "Wave 2 execution - verified manually"
+done
+```
+
+### Attesting Failures
+
+Document why a gate failed:
+
+```bash
+lex-pr gate attest \
+  --item "pr-999" \
+  --gates "security-scan" \
+  --status "fail" \
+  --reason "Known CVE-2024-12345 - will fix in next PR"
+```
+
+## Troubleshooting
+
+### "0 items eligible to merge" after attestation
+
+**Check:**
+
+1. Ensure gate result files were created in the correct directory
+2. Verify item names match plan.json
+3. Confirm all required gates are attested (check plan policy)
+
+```bash
+# List created gate results
+ls -la .smartergpt/gate-results/
+
+# Validate a gate result file
+lex-pr gate-report validate .smartergpt/gate-results/pr-650-build.json
+```
+
+### Gate results not loaded
+
+The MCP server and merge commands automatically look for gate results in:
+
+- `.smartergpt/gate-results/` (default)
+- Custom directory specified in profile
+
+Make sure your gate results are in the expected location.
+
+## Best Practices
+
+1. **Always provide a reason**: The `--reason` flag creates an audit trail for manual attestations
+2. **Use consistent item naming**: Match the item names in your plan.json exactly
+3. **Document CI integration**: When importing from CI, include build IDs and commit SHAs in metadata
+4. **Validate before merging**: Always run `merge --dry-run` first to check eligibility
+5. **Store gate results**: Keep gate result files in version control for traceability
+
+## Related Commands
+
+- `lex-pr gate execute` - Run gates using lexrunner (automatic tracking)
+- `lex-pr gate-report validate` - Validate gate result files
+- `lex-pr weave report` - Aggregate and display gate reports
+- `lex-pr merge` - Apply merge operations based on gate eligibility
+
+## See Also
+
+- [Merge Weave Quick Start](../MERGE_WEAVE_QUICKSTART.md)
+- [Gate Report Schema](../src/schema/gateReport.ts)
+- Issue #[number] - Gate result import feature