@smartergpt/lexrunner 1.0.0

package/AGENTS.md

@@ -0,0 +1,402 @@
+# AGENTS.md — lexrunner
+
+> **North Star**
+> **Fan-out tasks as multiple PRs in parallel, then build a merge pyramid from the blocks.
+> Compute dependency order, run gates locally, and merge cleanly.**
+
+This document orients all agents (human and automated) toward the same purpose and defines the
+non‑negotiable operating rules for **lexrunner**. It is intentionally **non task‑specific** and
+should remain stable even as implementation details evolve.
+
+---
+
+## 0) Core Premise (Do Not Drift)
+
+1. **Deterministic Program for Merges.** At **integration time**, the runner consumes a **single frozen input** (`plan.json`, Schema v1), executes a **deterministic merge plan**, and emits verifiable artifacts.
+   **Important scope note:** This “single input” constraint applies **only to the integration runner**. It **does not** limit how issues are defined or how implementation work is done.
+2. **Merge Pyramid.** Decompose work into many small PRs, compute a **dependency‑ordered pyramid** (topological order), and integrate bottom‑up.
+3. **Uniform Gates.** Execute the same **gates** (lint/type/test, policy checks, etc.) **locally and in CI**, with the same inputs and expectations.
+4. **Two‑Track Separation (Firm).**
+   - **Core runner** lives in the repository root (`src/*`, CLI, MCP adapter, packaging, CI). It is **stateless** and **packageable**.
+   - **`.smartergpt/` is a portable user workspace** and canonical profile. It is **not read at runtime** by the runner. It can contain example profiles, prompts, policies, and developer tooling.
+5. **Reproducibility Over Magic.** No hidden state, no “auto inference.” Integration inputs are explicit; outputs are traceable.
+6. **Auditability.** Every decision is inspectable (plan, gates, logs, outcomes).
+
+> ### Clarification: Scope of “Only Runtime Truth”
+>
+> - **Integration-time (Runner):** `plan.json` is the **only** input the runner reads to compute order and merges.
+> - **Development-time (Issues & Coding):** Implementation agents (humans/Copilot) are expected to use **Issue descriptions, specs, and project principles** to do the work. The runner does not constrain this phase.
+
+---
+
+## 1) Lifecycle & Surfaces (Who uses what, when)
+
+**Stage A — Issue Definition**
+
+- _Owners:_ PM/Author
+- _Surfaces:_ GitHub Issues / ADRs / specs
+- _Artifacts:_ Clear acceptance criteria, rationale, links
+
+**Stage B — Implementation Work**
+
+- _Owners:_ Humans & Copilot (implementation agents)
+- _Surfaces:_ Branches/PRs, tests, docs, `.smartergpt/` workspace tools
+- _Inputs:_ Issue descriptions + project principles (this document)
+- _Outputs:_ One or more focused PRs per task
+
+**Stage C — Plan Synthesis (Out of Runner Scope)**
+
+- _Owner:_ Plan‑generator tool or workflow
+- _Inputs:_ Graph of PRs, declared dependencies, policy, optional metadata from Issues
+- _Output:_ **`plan.json` (Schema v1)** — the frozen integration input
+
+**Stage D — Integration Runner (This Project)**
+
+- _Owner:_ lex‑pr‑runner (TS core)
+- _Input:_ `plan.json` only
+- _Behavior:_ Compute topo order, run gates uniformly, respect policy, merge cleanly
+- _Artifacts:_ Gate logs (JUnit/SARIF/etc.), status tables, PR comments
+
+**Stage E — Merge & Release**
+
+- _Owner:_ Maintainers/automation
+- _Artifacts:_ Changelog, tags, release notes
+
+---
+
+## 2) Runner Contract (Integration-Time)
+
+- **Single Runtime Input (Scoped):** `plan.json` (Schema v1) is the **only** integration input the runner reads.
+  _Development agents remain free to use Issues, ADRs, or other docs._
+- **Outputs:** Deterministic artifacts (gate results, merge decisions). Post as **PR comments or CI artifacts**, **not** as code changes in the runner path.
+- **Side‑Effects:** Only those declared in `plan.json` (e.g., which PR to merge, in what order). No implicit network calls or mutations.
+- **Idempotence:** Same `plan.json` → same decisions (modulo external state, e.g., a PR already merged).
+
+---
+
+## 3) Plan Model (Schema v1 — High Level Contract)
+
+- **Nodes:** PRs/commits with identifiers, metadata, and **declared dependencies**.
+- **Edges:** Dependencies only (no implicit ordering).
+- **Gates:** Named checks per node (e.g., `lint`, `type`, `unit`, `e2e`, `policy`). Each gate has a command/adapter reference and expected status semantics.
+- **Policy:** Merge rules (e.g., “all required gates green,” “no fast‑forward across failing siblings,” “block on security policy violations”).
+- **Outputs:** Expected artifacts per gate (logs, JUnit, coverage, SARIF, etc.).
+
+#### Policy Examples (Non-Normative)
+
+```yaml
+requiredGates: ["lint", "type", "unit"]
+optionalGates: ["e2e"]
+maxWorkers: 2
+retries:
+  e2e: { maxAttempts: 2, backoffSeconds: 30 }
+overrides:
+  adminGreen:
+    allowedUsers: ["repo-admins"]
+    requireReason: true
+security:
+  # Fix ALL vulnerabilities when patches are available (see §16)
+  blockOnFixableVulnerability: true
+  trackSeverities: ["critical", "high", "moderate", "low"]
+mergeRule:
+  # “All required gates green; optional gates ignored unless specified”
+  type: "strict-required"
+```
+
+#### Schema Versioning
+
+- Plans must include `"schemaVersion": "1.x.y"`.
+- Versioning follows SemVer:
+  - **Patch:** additive, optional fields or docs only.
+  - **Minor:** additive required fields with safe defaults.
+  - **Major:** breaking changes to structure or semantics.
+- The runner refuses plans with unknown **major** versions.
+
+_Anything not in the plan is out of scope for the runner._
+
+---
+
+## 4) Merge Pyramid & Ordering Rules
+
+1. **Topological Sort:** Compute an order from leaves → root such that a node runs only after all dependencies are green.
+2. **Parallelism:** Independent subgraphs may run concurrently **up to the concurrency limits** specified by policy/plan.
+3. **Promotion:** A node is eligible to merge when all **required gates** pass and **policy** authorizes.
+4. **Short‑Circuiting:** If a dependency fails on required gates, **do not** run dependents (mark as blocked).
+
+### Runner State Model (Statuses)
+
+| Status     | Meaning                                              | Merge Eligibility |
+| ---------- | ---------------------------------------------------- | ----------------- |
+| `pass`     | All required gates passed                            | Eligible          |
+| `fail`     | One or more required gates failed                    | Not eligible      |
+| `blocked`  | A dependency failed/blocked; node not executed       | Not eligible      |
+| `skipped`  | Policy or config excludes gates for this node        | Not eligible      |
+| `retrying` | Gate marked retryable; attempt in progress (bounded) | Not eligible      |
+
+### Umbrella Branch Pattern (When Main is Blocked)
+
+When branch protection or pending approvals block direct merges to `main`, use an **umbrella branch**:
+
+1. **Create umbrella branch:** `integration/umbrella-YYYYMMDD` or similar
+2. **Merge-weave into umbrella:** Apply normal topo-sort and gate execution
+3. **Umbrella builds foundation:** All PRs merge to umbrella, conflicts resolved there
+4. **Final umbrella → main:** This single PR goes through full gates and approval
+5. **Authority:** Eager PM may authorize the final merge when local CI passes
+
+**Key insight:** Individual PR blocks don't matter during weave—we're building a verified bundle.
+The constraint applies only to the **final push to main**.
+
+---
+
+## 5) Gates — Uniform Execution
+
+- **Same Everywhere:** Gate execution logic and defaults must match **local and CI**.
+- **Stable Interfaces:** Each gate produces structured results (status, duration, artifacts, logs). Prefer machine‑readable outputs (JUnit, SARIF) in addition to human logs.
+- **Exit Codes & Semantics:** `0` = pass, `>0` = fail; distinguish “blocked” vs “failed” in the runner’s state model.
+- **Caching (Optional):** Allowed, but must not change semantics. Cache keys should derive from inputs/artifacts so replays are consistent.
+
+---
+
+## 6) Two‑Track Separation (Enforced)
+
+- **Core Runner (Track A):** `src/`, CLI, adapters (e.g., MCP), packaging, CI recipes. _Never_ hard‑link or read `.smartergpt/` at runtime.
+- **Portable Workspace (Track B):** `.smartergpt/` contains examples, profiles, prompts, policies, local tooling, and deliverables for **humans and agents**. It is **replaceable** and **repo‑portable**.
+
+**Why this matters:** Repos can adopt lex‑pr‑runner without inheriting your personal workspace, and your workspace can travel across repos without changing the runner. This is the foundation for determinism and portability.
+
+---
+
+## 7) Agent Roles
+
+- **Implementation Agents (Humans/Copilot):** Build the code guided by Issues and project principles; produce small PRs with explicit dependencies.
+- **Plan Generator (Out of Runner Scope):** Transforms Issues/PR graph into `plan.json`. May live in a separate tool or workflow.
+- **Runner Core Agent:** Maintains the TS source of truth (Zod schemas, topo logic, CLI). Guards determinism and contracts.
+- **Gate Executors:** Implement gate adapters/commands; ensure uniform behavior local/CI; publish structured artifacts.
+- **MCP Adapter Agent:** Provides a clean interface for external tools/orchestrators; adheres to the runner contract.
+- **Documentation Agent:** Keeps `README.md`, `AGENTS.md`, and policy docs current with behavior and contracts (not implementation churn).
+
+---
+
+## 8) Operational Rules (Do / Don’t)
+
+**Do**
+
+- Treat `plan.json` as the **only integration‑time input** for the runner.
+- Keep the runner **stateless**; derive integration state from inputs and external APIs declared in the plan.
+- Prefer **pure functions** and small modules. TS‑first with Zod schemas.
+- Emit artifacts to **deliverables or PR comments**, not into source directories.
+- Uphold **imperative commit messages** (e.g., “Add…”, “Fix…”, “Refactor…”).
+
+**Don’t**
+
+- Don’t read `.smartergpt/` at runtime.
+- Don’t infer dependencies from file paths or heuristics. Only the plan decides.
+- Don’t hide side‑effects behind environment variables. All effects must be declared in the plan or policy.
+- Don’t fork logic between local and CI paths.
+
+---
+
+## 9) Failure Handling & Recovery
+
+- **Gate Failure:** Mark node `failed`; propagate `blocked` status to dependents. Surface logs and artifacts.
+- **Flakes:** If a gate is marked “retryable” by policy, bound the retries and always record attempts.
+- **External Errors (API/outage):** Classify separately from test failures; do not merge on ambiguous state.
+- **Manual Overrides:** Allowed only through explicit policy hooks (e.g., “admin green”). All overrides are logged with rationale.
+
+---
+
+## 10) Observability & Artifacts
+
+- **Where:** Post structured results as PR comments and/or CI artifacts. Keep **diagnostics out of the runner’s source tree**.
+- **What:** Status tables, dependency graphs, gate summaries, links to detailed logs (JUnit, SARIF, coverage, HTML reports).
+- **Why:** Auditable paper trail and reproducible investigations.
+
+---
+
+## 11) CI Alignment & Least-Privilege
+
+- **Same entrypoints:** CI invokes the same runner CLI as local.
+- **Tokens:** Grant only what's needed for status + merges (`contents:read`, `pull_requests:write`, `statuses:write`); avoid admin scopes.
+- **Isolation:** Run gates in containers where feasible for reproducibility.
+- **Failure is final:** Required gate failure fails the job; no silent retries unless policy permits.
+- **Compose/workflow skeleton:** Provide templates that spin up only what's needed for gates.
+- **Contract compliance:** Fail the job if any required gate fails or if the plan contract is violated.
+- CI must run the **same** CLI entry points as local.
+- Provide a **compose/workflow skeleton** that spins up only what’s needed for gates.
+- Fail the job if **any required gate** fails or if the **plan contract** is violated.
+
+---
+
+## 12) Coding Conventions (TS‑First)
+
+- **Language:** TypeScript.
+- **Schemas:** Zod. Export parse/validate helpers.
+- **CLI:** Commander (or equivalent) with stable flags; avoid breaking changes.
+- **Style:** Small, testable modules; deterministic pure logic around topo/gates; adapters isolate side‑effects.
+- **Tests:** Unit tests for topo/gates; fixture‑based tests for plan parsing and policy.
+
+---
+
+## 13) Checklists
+
+### PR Author
+
+- [ ] Break work into small, independently reviewable PRs.
+- [ ] Declare dependencies explicitly in PR descriptions and/or `plan.json` pre‑cursor metadata.
+- [ ] Ensure required gates are defined and runnable.
+
+### Agent (Runner/Gate)
+
+- [ ] Validate `plan.json` against Schema v1.
+- [ ] Compute topo order; verify DAG (no cycles).
+- [ ] Execute gates uniformly; collect artifacts.
+- [ ] Respect policy; merge only when eligible.
+- [ ] Emit artifacts/logs outside source; post results back to PR.
+
+### Release
+
+- [ ] Tag runner version & schema version.
+- [ ] Changelog: note contract changes explicitly.
+- [ ] Verify CI template and local flows match.
+
+---
+
+## 14) FAQ
+
+**Q: Why doesn’t the runner read Issues directly?**
+A: To keep integration **deterministic and replayable**. Issues can change without a commit; `plan.json` freezes the intent for a run.
+
+**Q: Can the plan generator ingest Issues?**
+A: Yes. The generator (separate tool) may read Issues/PR metadata to **produce** `plan.json`. The runner still only consumes the plan.
+
+**Q: Does this block exploratory or Copilot‑led development?**
+A: No. Implementation agents use Issues/specs as usual. The constraint applies only at **integration time**.
+
+---
+
+**How do I declare PR dependencies?**
+Use a `Depends-on: #<PR>` footer (or labels). The plan generator resolves these into `node.dependsOn`.
+
+**What if my gates need secrets?**
+Provide them via CI secrets/env; do not let secrets alter gate semantics. Prefer containerized gates.
+
+**Can I use this with our existing CI?**
+Yes. Keep your CI; point it at the runner CLI. The runner remains deterministic because it only consumes `plan.json`.
+
+## 15) Invariants (Quick Reference)
+
+- Runner reads **only `plan.json`** at integration time.
+- `.smartergpt/` is never a runtime dependency.
+- Local and CI gate semantics are identical.
+- No hidden side‑effects; everything is declared.
+- Same inputs → same outputs.
+
+#### CI-Bound Resources & Environments
+
+Some gates need secrets (e.g., databases, SaaS tokens) or services unavailable locally.
+
+- **Runtime selector (suggested):** `gate.runtime = "local" | "container" | "ci-service"`
+- **Containerization (recommended for parity):** If `runtime = container`, include `image`, `entrypoint`, and `mounts` in the plan or policy.
+- **Secrets & env:** Gate adapters may read env vars **only** to locate credentials; secrets must not change gate semantics.
+- **Example gate spec (non-normative):**
+
+```json
+{
+  "name": "e2e",
+  "runtime": "container",
+  "image": "ghcr.io/acme/e2e:1.4.2",
+  "command": ["npm", "run", "e2e"],
+  "artifacts": ["junit.xml", "screenshots/"]
+}
+```
+
+---
+
+## Appendix C — Plan Generator Reference (Non-Normative)
+
+**Purpose:** Show how teams can go from Issues/PRs → `plan.json` without constraining the runner.
+
+### Dependency Declaration (PR metadata)
+
+- Footer syntax (suggested): `Depends-on: #123, #456`
+- Label-based (alternative): `dep:123`, `dep:456`
+- The generator resolves PR numbers → node IDs.
+
+### Field Mapping (example)
+
+| Source                | Plan field             |
+| --------------------- | ---------------------- |
+| PR number             | `node.id`              |
+| PR title              | `node.title`           |
+| PR labels             | `node.tags[]`          |
+| `Depends-on:` footer  | `node.dependsOn[]`     |
+| Required checks label | `node.requiredGates[]` |
+
+### Minimal `plan.json` example
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "policy": { "requiredGates": ["lint", "type", "unit"], "maxWorkers": 2 },
+  "nodes": [
+    { "id": "PR-101", "title": "Core utils", "dependsOn": [], "gates": ["lint", "type", "unit"] },
+    {
+      "id": "PR-202",
+      "title": "Feature A",
+      "dependsOn": ["PR-101"],
+      "gates": ["lint", "type", "unit"]
+    }
+  ]
+}
+```
+
+---
+
+## Appendix D — Quick Start (Happy Path)
+
+1. **Open Issues** with crisp acceptance criteria.
+2. **Implement** in **small PRs**; add `Depends-on:` footers if needed.
+3. **Generate plan:** Run your plan generator to emit `plan.json`.
+4. **Dry run locally:** `lexrunner --plan plan.json --dry-run`
+5. **Run gates:** Same CLI locally and in CI; confirm artifacts appear under `<nodeId>/<gateName>/`.
+6. **Merge pyramid:** Runner computes topo order, merges eligible nodes.
+7. **Commit messages:** Imperative mood (e.g., “Add…”, “Fix…”).
+
+## 16) Security Dependency Policy
+
+**Always fix security vulnerabilities when a fix is available.**
+
+This applies to all severity levels (critical, high, moderate, low). Rationale:
+
+- **No severity is "safe to ignore."** Even low-severity issues can be chained or escalated.
+- **Fixes are cheap.** If `npm audit fix` or equivalent resolves it, do it immediately.
+- **Technical debt compounds.** Deferred security fixes become harder to untangle over time.
+
+### Workflow
+
+1. **Check for vulnerabilities:** `npm audit` (or equivalent for your package manager)
+2. **If fix available:** Apply it (`npm audit fix`) and commit immediately
+3. **If no fix available:** Document in a tracking issue with rationale for deferral
+4. **Dependabot PRs:** Merge promptly when CI passes (or is pending, not failing)
+
+### Policy Configuration (Non-Normative)
+
+```yaml
+security:
+  # Block merges when ANY unfixed vulnerability has an available patch
+  blockOnFixableVulnerability: true
+  # Severity levels to track (all by default)
+  trackSeverities: ["critical", "high", "moderate", "low"]
+  # Auto-merge dependabot PRs when CI is green or pending
+  autoMergeDependabot: true
+```
+
+---
+
+## 17) Environment Stability (WSL2/CI)
+
+- **Resource Limits:** Test runners (Vitest) must be configured with explicit concurrency limits (`maxWorkers: 1`) to prevent resource exhaustion in constrained environments like WSL2 or shared CI runners.
+- **Crash Prevention:** Avoid unbounded recursion or excessive memory allocation in tests.
+- **Process Isolation:** Ensure tests clean up temporary directories and processes.
+- **Git Configuration:** Tests creating git repositories MUST explicitly disable GPG signing (`git config commit.gpgsign false`) to prevent interactive prompts that hang the test runner and crash the environment.
+- **Git Tests:** Tests that perform git commits or require a git environment are EXCLUDED from the default `npm test` run. Run them explicitly with `npm run test:git`. These tests MUST NOT run in CI.

package/CHANGELOG.md

@@ -0,0 +1,256 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres (prospectively) to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+_No unreleased changes._
+
+---
+
+## [1.0.0] - 2026-01-04
+
+### 🎉 First Stable Release
+
+LexRunner reaches 1.0.0 with comprehensive merge-weave automation, enterprise onboarding, and robust gate execution.
+
+### Added
+
+- **Post-merge Type Check Gate** - Catch integration breaks early with automatic type checking after merges
+- **Auto-update PR Branches** (#693) - Automatically update PR branches during sequential merge-weave
+- **Batch Issue State Checking** - Parallel API calls with TTL caching for faster state checks
+- **Enterprise Onboarding Wizard** (#692) - Unified setup experience for new users
+- **Import Gate Results from GitHub** (#691) - Import check run results as gate attestations
+- **Auto-undraft Copilot Agent PRs** (#690) - Automatically mark Copilot PRs ready when complete
+- **Agent Stall Detection** (#689) - Automatic nudging when agents stall
+- **Checkpoint and Resume** (#688) - Resume interrupted merge-weave operations
+- **Inter-PR Conflict Detection** (#681) - Detection and resolution guidance for PR conflicts
+- **Gate Attestation and Import** (#680) - Record external gate runs
+- **D2 Executor** (#675, #677) - Draft promotion and multi-repo plan support
+- **Counter-example Capture** (LR-TSF-003) - Capture gate failure examples for learning
+- **Constraint Preview in Dry-run** (LR-TSF-002) - Preview constraints before execution
+- **Constraint Attribution** (LR-TSF-001) - Track which rules produced which constraints
+- **Fanout Harvest/Analyze Tools** (Epic #654) - MCP tools for Copilot agent fanout
+
+### Removed
+
+- All deprecated `lexrunner_*` MCP tool aliases (use canonical names)
+
+---
+
+## [0.6.0] - 2025-12-16
+
+### ⚠️ BREAKING CHANGE: MCP Tool Names
+
+**VS Code automatically adds `mcp_{servername}_` prefix to all tool names.** Our previous naming included redundant prefixes, causing tools to appear as `mcp_lexrunner_lexrunner_plan_create` instead of `mcp_lexrunner_plan_create`.
+
+This release removes the namespace prefix from tool definitions to match the GitHub MCP pattern.
+
+#### Migration Guide
+
+| v0.5.x Tool Name              | v0.6.x Tool Name  | VS Code Display                 |
+| ----------------------------- | ----------------- | ------------------------------- |
+| `lexrunner_plan_create`       | `plan_create`     | `mcp_lexrunner_plan_create`     |
+| `lexrunner_gate_run`          | `gates_run`       | `mcp_lexrunner_gates_run`       |
+| `lexrunner_weave_apply`       | `merge_apply`     | `mcp_lexrunner_merge_apply`     |
+| `lexrunner_weave_discover`    | `discover`        | `mcp_lexrunner_discover`        |
+| `lexrunner_weave_status`      | `weave_status`    | `mcp_lexrunner_weave_status`    |
+| `lexrunner_weave_order`       | `merge_order`     | `mcp_lexrunner_merge_order`     |
+| `lexrunner_workspace_init`    | `local_init`      | `mcp_lexrunner_local_init`      |
+| `lexrunner_workspace_resolve` | `profile_resolve` | `mcp_lexrunner_profile_resolve` |
+| `lexrunner_workspace_doctor`  | `doctor`          | `mcp_lexrunner_doctor`          |
+| `lexrunner_core_health`       | `health`          | `mcp_lexrunner_health`          |
+| `lexrunner_core_config`       | `config_show`     | `mcp_lexrunner_config_show`     |
+| `lexrunner_core_guide`        | `workflow_guide`  | `mcp_lexrunner_workflow_guide`  |
+| `lexrunner_core_metrics`      | `metrics`         | `mcp_lexrunner_metrics`         |
+| `lexrunner_executor_*`        | `executor_*`      | `mcp_lexrunner_executor_*`      |
+| `lexrunner_run_start`         | `start_run`       | `mcp_lexrunner_start_run`       |
+| `lexrunner_run_status`        | `get_status`      | `mcp_lexrunner_get_status`      |
+| `lexrunner_run_list`          | `list_artifacts`  | `mcp_lexrunner_list_artifacts`  |
+| `lexrunner_run_decision`      | `run_decision`    | `mcp_lexrunner_run_decision`    |
+
+**Backwards Compatibility:** Old `lexrunner_*` names are preserved as deprecated aliases and will continue to work. They will be removed in v1.0.0.
+
+### Added
+
+- Governance wrapper delegation tests: validates `scripts/analyze-governance-logs.mjs` correctly delegates to CLI
+
+### Changed
+
+- MCP tool names no longer include namespace prefix (GitHub MCP pattern)
+- LexSona rule injection now enabled by default with environment variable configuration
+- Updated `loadLexSonaRules()` API to use `RuleInjectionConfig` object instead of boolean parameter
+- Removed legacy runner/ location fallback for config files in bootstrap
+
+### Fixed
+
+- Tools now display correctly in VS Code as `mcp_lexrunner_{action}` instead of `mcp_lexrunner_lexrunner_{action}`
+
+### Documentation
+
+- Updated LexSona rules documentation with v0.5.0 API changes
+- Documented remaining compatibility shims with removal timeline (v2.0.0)
+- Updated QOL-COMPLETION-REPORT.md with governance consolidation reality check:
+  - `governance:report` is the canonical analysis command
+  - `scripts/analyze-governance-logs.mjs` is a backwards-compatibility wrapper
+  - Schema versioning is semver-based with legacy normalization via `--accept-legacy`
+  - Dedicated `--quiet-shadow` flag is deferred (use global `--quiet`)
+
+### Removed
+
+- `src/cli-old.ts` dead code (old CLI implementation, was already excluded from build)
+- Deprecated `migrateGateReport` alias (use `normalizeGateReport` instead)
+
+---
+
+## [0.5.0] - 2025-11-27
+
+### Added
+
+- Autopilot Levels 0–4 with progressive feature set (planning, safety, merge simulation, deliverables, compliance reporting).
+- Deliverables management system: manifests, retention policy, symlinked latest, custom directory via `--deliverables-dir`.
+- Gate Report JSON Schema (`gate-report.schema.json`) and validation command (`gate-report validate`).
+- Security & compliance reporting foundation with signing, integrity verification, and audit artifacts.
+- Deterministic plan hashing & reproducibility safeguards (canonical JSON ordering, build determinism check guidance).
+- Extensive documentation suite: architecture, CI/CD integration, deliverables management, plan generation, troubleshooting, performance scaling, migration guide.
+- New tests: deliverables lifecycle, extended autopilot E2E coverage, gate report schema validation, security compliance scenarios.
+- **Procedure Library:** Config-driven state machines for merge-weave and other workflows.
+  - `ProcedureLoader` API for loading procedures from YAML.
+  - `ProcedureStateMachine` for state transitions and decision points.
+  - `merge-weave-main.yaml` canonical procedure definition.
+
+### Changed
+
+- CLI autopilot command deduplicated options and removed merge conflict artifacts.
+- Standardized exit behavior and error messaging across autopilot and gate validation paths.
+- Refined documentation structure; consolidated implementation summary and security sections.
+
+### Fixed
+
+- Resolved merge conflicts in `IMPLEMENTATION_SUMMARY.md` and `src/cli.ts` (duplicate option & duplicate execution call).
+- Addressed minor drift in documentation references after feature merges.
+- Closed Issue #456: Procedure schema now matches merge-weave-main.yaml format.
+
+### Documentation
+
+- Closed documentation gap (Issue #103) with enriched guides (`docs/*.md`).
+- Added detailed deliverables management guide and CI/CD integration examples.
+- Updated terminology references aligning with `AGENTS.md` and `TERMS.md`.
+- **@experimental markings:** Autopilot L3-L4 marked as experimental, subject to breaking changes.
+- **@internal markings:** Procedure library marked as internal, format may change between versions.
+
+### Testing
+
+- Increased total passing tests to 2970+ with new suites for deliverables, schema validation, and compliance.
+- Added fixtures for plan validation edge cases (cycles, unknown dependencies, invalid schema).
+- Procedure loader tests (35 tests) covering schema validation, semantics, and state machine.
+
+### Security
+
+- Established baseline security verification (integrity signing, audit logs) — sets stage for Phase 2 (Issue #129).
+
+### Deprecated
+
+- Legacy duplicated autopilot CLI logic (removed). No formal deprecations yet.
+
+### Removed
+
+- Merge artifact duplicate `--deliverables-dir` option and redundant `autopilot.execute()` call.
+
+### Internal
+
+- Issue triage and closure: #74 (Autopilot Levels), #90 (Gate Report Schema), #96 (Extended Autopilot), #103 (Documentation), #456 (Procedure Schema) closed.
+- Opened follow-up tracking issues: #128 (CLI UX), #129 (Security Phase 2), #130 (Test Infra Phase 2), #131 (Config Expansion), #132 (Release Pipeline), #133 (Planner Auto-Discovery), #134 (Contributor Onboarding).
+
+## [0.1.0] - 2025-11-06
+
+**First Stable Release** — Establishes product branding and Frame emission foundation.
+
+### Added
+
+#### Product Branding
+
+- **ADR-000:** Product Naming & Branding decision (LexRunner proprietary vs Lex MIT OSS).
+- README branding and badge updates for LexRunner identity.
+- Release workflow on `lexrunner-v*` tag pattern for deterministic versioning.
+- Architecture Decision Record (ADR) directory and index in `docs/adr/`.
+- Clear separation between LexRunner (proprietary) and Lex (MIT OSS core).
+
+#### Frame Emission System
+
+- Frame emitter utilities in `src/frames/emitter.ts` for workflow execution tracking.
+- Frame storage to `.lexrunner/frames/` directory with atomic writes.
+- Frame types: merge-weave, gate, executor, and procedure frames.
+- Frame validation schema with outcome tracking (success, partial, failure).
+- Optional Frame emission controlled via `LEX_PR_EMIT_FRAMES` environment variable (default: `false`).
+- Audit trail capabilities for workflow history and debugging.
+
+#### Documentation
+
+- Migration guide for v0.1 (`docs/MIGRATION_v0.1.md`) with:
+  - Frame emission enablement instructions
+  - Before/after examples
+  - Troubleshooting section
+  - CI/CD integration examples
+- ADR-000 documenting product naming and release tag conventions.
+- Lex (MIT OSS) cross-reference in README.
+- Badges for licensing clarity (Proprietary + Powered by Lex).
+- "Branding & Licensing" section with link to ADR-000.
+- Link to module aliasing documentation for future Lex integration.
+
+### Changed
+
+- README header now prominently displays "LexRunner — Merge-Weave & Fanout CLI (`lex-pr`)".
+- Release workflow condition updated to trigger on `lexrunner-v*.*.*` tags (not legacy `v*` format).
+- Product name standardized to "LexRunner" in all documentation.
+
+### Fixed
+
+- N/A (first stable release)
+
+### Breaking Changes
+
+- **None** — All changes are additive and maintain backward compatibility.
+
+### Deprecated
+
+- **None** — This is the initial stable release.
+
+### Security
+
+- Frame storage uses atomic file writes (temp file + rename) to prevent corruption.
+- Frame validation ensures data integrity before storage.
+
+### Migration Notes
+
+**From Pre-Release:**
+
+1. No breaking changes; all existing workflows continue to work.
+2. Frame emission is **disabled by default**; opt-in via `export LEX_PR_EMIT_FRAMES=true`.
+3. Release tags now use `lexrunner-v*` format; old `v*` tags deprecated.
+4. Update documentation references to use "LexRunner" (product) and "Lex" (OSS core) appropriately.
+
+See [Migration Guide](docs/MIGRATION_v0.1.md) for complete upgrade instructions.
+
+### Known Limitations
+
+- Frame emission to Lex memory API not yet implemented (planned for v0.2+).
+- Module aliasing for Frames not yet available (planned for v0.2+).
+- Frame query/recall tools not yet implemented (planned for future releases).
+
+### Related Issues
+
+- Epic E: Paid-vs-free split, CI gates, and release notes
+- LPR-010: Sub E.3: Migration guide and release notes for v0.1
+
+---
+
+### Release Process (Preview)
+
+Planned automation (Issue #132) will generate future entries via a `release:prepare` script parsing conventional commits. Until then, updates are manual but must remain deterministic and audit-friendly.
+
+### Verification Notes
+
+For each unreleased change, gates (lint, type, unit) pass locally and in CI; plan hashing and artifact determinism validated via reproducible builds (`npm run build && npm run format` => clean git tree).