docs: prior-session audit + contributor workflow + Makefile target fixes

Final batch of prior-session docs left in the working tree:

- docs/current-state.md: implementation audit dated 2026-04-15.
  Snapshot of strengths, risks, missing pieces, and the
  recommendation that became the issue 03 / shared config parser
  work. Cross-referenced from architecture-and-status.md (which
  supersedes it as the entry point).
- docs/superpowers/specs/2026-04-15-implementation-gap-backlog-design.md:
  the design that established the local docs/issues/ backlog (P0/P1/P2).
- AGENTS.md: contributor workflow, naming, and validation
  expectations.
- README.md: adds a Documentation Map section pointing at the four
  docs above + benchmarks + the historical specs/plans tree.
  Fixes the Makefile target names in the Tools table that had
  drifted (build-mysql-server -> mysql-server, build-engine-stress
  -> engine-stress, build-bench-distributed -> bench-distributed).
- CLAUDE.md: same Makefile target name fixes.

Also removes tmp_apply_patch_check.txt (a one-line "hello" stray
file from an interrupted edit cycle).

No code changes.

Author: renecannao

AGENTS.md

@@ -0,0 +1,24 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Core parser headers live in `include/sql_parser/` and parser implementations in `src/sql_parser/`. SQL engine, remote execution, and transaction interfaces live in `include/sql_engine/` with implementations in `src/sql_engine/`. Tests are in `tests/`, mostly as focused `test_<area>.cpp` files plus `corpus_test.cpp` for large parser corpora. Developer tools live in `tools/`, automation scripts in `scripts/`, benchmark reports in `docs/benchmarks/`, and vendored dependencies in `third_party/`.
+
+## Build, Test, and Development Commands
+Use the `Makefile` as the source of truth:
+
+- `make all` builds `libsqlparser.a` and runs the full GoogleTest suite.
+- `make test` rebuilds `run_tests` and executes all tests locally.
+- `make lib` builds just the static library.
+- `make build-sqlengine` builds the interactive CLI as `./sqlengine`.
+- `make build-corpus-test` builds `./corpus_test` for external SQL corpus validation.
+- `make bench` runs the benchmark binary; use it for parser or executor performance changes.
+- `make clean` removes generated objects and binaries.
+
+## Coding Style & Naming Conventions
+This repository is C++17 with warnings enabled via `-Wall -Wextra`. Match the existing style: 4-space indentation, opening braces on the same line, and concise comments only where the code is not obvious. Use `PascalCase` for types, `snake_case` for functions and methods, `UPPER_SNAKE_CASE` for include guards and macros, and keep file names module-oriented such as `parser.cpp`, `distributed_txn.h`, and `test_select.cpp`. There is no repo-wide formatter config outside vendored code, so follow surrounding files closely.
+
+## Testing Guidelines
+Tests use GoogleTest through `tests/test_main.cpp`. Add coverage in the nearest existing `test_<feature>.cpp`, or create a new file with that pattern if the area is new. Prefer small, focused `TEST` or `TEST_F` cases that mirror the production module name. Run `make test` before opening a PR; for grammar or dialect work, also run `make build-corpus-test`.
+
+## Commit & Pull Request Guidelines
+Recent history uses short conventional prefixes such as `feat:`, `fix:`, `test:`, `docs:`, and `chore:`. Keep commit titles imperative and specific, for example `feat: add UTC normalization for PgSQL timestamps`. PRs should target `main`, explain parser/engine behavior changes, list the commands you ran, and link related issues. Include benchmark or corpus-test notes when performance or SQL coverage changes. Do not commit generated `.o` files, binaries, or benchmark artifacts.

CLAUDE.md

@@ -23,7 +23,9 @@ make bench              # Build + run benchmarks
 make bench-compare      # Run comparison vs libpg_query (requires libpg_query built)
 make build-corpus-test  # Build corpus test harness
 make build-sqlengine    # Build interactive SQL engine CLI
-make build-mysql-server # Build MySQL wire-protocol server
+make mysql-server       # Build MySQL wire-protocol server
+make engine-stress      # Build direct-API stress harness
+make bench-distributed  # Build distributed benchmark tool
 make clean              # Remove all build artifacts
 ```
 

README.md

@@ -211,6 +211,15 @@ auto report = recovery.recover();
 // report.recovered_commit, recovered_rollback, still_in_doubt, ...
 ```
 
+## Documentation Map
+
+- `README.md` — product overview, quick start, build, tools, and test entry points.
+- [`docs/current-state.md`](docs/current-state.md) — current implementation audit, strengths, risks, missing docs, and recommended next step.
+- `CLAUDE.md` — maintainer/agent architecture notes with file-level extension guidance.
+- `AGENTS.md` — contributor workflow, naming, and validation expectations.
+- `docs/benchmarks/` — latest benchmark reports plus reproduction instructions.
+- `docs/superpowers/specs/` and `docs/superpowers/plans/` — historical design and planning artifacts; useful for rationale, but not the source of truth for current behavior.
+
 ## Architecture
 
 ```
@@ -360,10 +369,10 @@ auto report = recovery.recover();
 | Tool | Build | Purpose |
 |---|---|---|
 | `sqlengine` | `make build-sqlengine` | Interactive SQL CLI; stdin, one-shot, or REPL; optional backends and sharding |
-| `mysql_server` | `make build-mysql-server` | MySQL wire-protocol server fronted by the ParserSQL engine |
+| `mysql_server` | `make mysql-server` | MySQL wire-protocol server fronted by the ParserSQL engine |
 | `corpus_test` | `make build-corpus-test` | Read SQL from stdin/files, parse each, report OK/PARTIAL/ERROR |
-| `engine_stress_test` | `make build-engine-stress` | Direct-API engine stress test |
-| `bench_distributed` | `make build-bench-distributed` | Distributed query benchmark + pipeline breakdown |
+| `engine_stress_test` | `make engine-stress` | Direct-API engine stress test |
+| `bench_distributed` | `make bench-distributed` | Distributed query benchmark + pipeline breakdown |
 | `run_bench` | `make bench` | Google-Benchmark micro-benchmarks |
 | `run_tests` | `make test` | 1,160 Google-Test unit tests |
 

docs/current-state.md

@@ -0,0 +1,66 @@
+# Current State
+
+## Documentation Inventory
+
+The repository already has useful documentation, but it is spread across several audiences:
+
+- `README.md` is the public overview and quick-start document.
+- `CLAUDE.md` is the most detailed architecture guide today; it is accurate in broad strokes, but it is written for coding agents and maintainers rather than new contributors.
+- `AGENTS.md` covers contributor workflow and repository conventions.
+- `docs/benchmarks/` contains benchmark outputs and reproduction notes.
+- `docs/superpowers/specs/` and `docs/superpowers/plans/` preserve design intent and implementation plans from earlier work.
+
+## Implementation Snapshot
+
+As of April 15, 2026, the codebase is a real four-layer system rather than just a parser prototype:
+
+1. Parser in `include/sql_parser/` and `src/sql_parser/`
+2. Query engine in `include/sql_engine/`
+3. Distributed execution and remote backends in `include/sql_engine/` and `src/sql_engine/`
+4. Transaction management, including 2PC, durable WAL, and recovery
+
+Operational entry points exist for interactive use and experiments: `sqlengine`, `mysql_server`, `bench_distributed`, `engine_stress_test`, and `corpus_test`.
+
+Fresh verification on April 15, 2026:
+
+- `./run_tests --gtest_brief=1`
+- Result: 1,197 tests ran, 1,160 passed, 37 skipped because live MySQL/PostgreSQL backends were not available locally
+
+## Strengths
+
+- Clear subsystem boundaries: parser, engine, distributed layer, and transactions are easy to identify from the directory layout.
+- Strong unit-test signal: 1,160 passing tests plus CI across Linux and macOS.
+- Useful performance discipline: benchmark tooling, published benchmark reports, and corpus validation are already part of the repository workflow.
+- Good internal architecture notes: `CLAUDE.md` gives maintainers practical file-level guidance for extending the system.
+
+## Weaknesses and Risks
+
+- Public docs had drifted from the `Makefile`; several tool build targets were named incorrectly until this update.
+- Documentation is fragmented. The most detailed design knowledge lives in `CLAUDE.md` and historical spec/plan files, not in one current contributor-facing document.
+- Several critical components are large, concentrated files or headers, especially `include/sql_engine/distributed_planner.h`, `include/sql_engine/plan_executor.h`, `src/sql_parser/parser.cpp`, and `tools/mysql_server.cpp`.
+- Backend URL parsing and related setup logic are duplicated across `tools/sqlengine.cpp`, `tools/mysql_server.cpp`, `tools/bench_distributed.cpp`, `tools/engine_stress_test.cpp`, and mirrored again in `tests/test_ssl_config.cpp`.
+- Some remote/distributed verification paths depend on live services, so local default test runs still skip meaningful backend coverage.
+
+## What Is Missing
+
+- A contributor-oriented local setup guide for running MySQL and PostgreSQL integration paths with the existing `scripts/`.
+- One authoritative architecture/status document before this file; maintainers had to reconstruct “current truth” from README, CLAUDE, code comments, and old plans.
+- A documented list of known limitations and non-goals for the parser, executor, and distributed transaction path.
+- A prioritized roadmap tying the current implementation to the next engineering milestone.
+
+## Recommended Next Step
+
+The highest-leverage next step is to consolidate backend/tool configuration into one shared module and document one supported local integration workflow around it.
+
+Why this should go first:
+
+- It removes copy-pasted parsing/setup logic from four tools and one test helper.
+- It reduces the chance that SSL, backend naming, or shard parsing diverges between entry points.
+- It creates a stable base for stronger end-to-end tests and clearer contributor setup docs.
+
+Suggested scope for that next phase:
+
+1. Extract backend URL and shard parsing into a shared utility under `include/sql_engine/` or `tools/`.
+2. Update `sqlengine`, `mysql_server`, `bench_distributed`, `engine_stress_test`, and `tests/test_ssl_config.cpp` to use the shared code.
+3. Add a short “local backend test workflow” doc that uses the existing `scripts/start_test_backends.sh` and related helpers.
+4. Add one smoke-level verification path that exercises a live backend with the shared configuration code.

docs/superpowers/specs/2026-04-15-implementation-gap-backlog-design.md

@@ -0,0 +1,40 @@
+# Implementation Gap Backlog Design
+
+**Goal:** Create a local, detailed issue backlog for the known implementation gaps and start execution from the highest-priority correctness issue.
+
+**Scope decision:** The implementation gaps are too broad to execute as one plan. They are decomposed into local issues in `docs/issues/`, with immediate execution limited to the first `P0` item.
+
+## Backlog Structure
+
+- Use `docs/issues/README.md` as the prioritized index
+- Use one Markdown file per issue for problem statement, evidence, scope, acceptance criteria, and verification
+- Keep the issue docs local-first so work can proceed without GitHub issue setup
+
+## Priority
+
+1. `P0`: distributed 2PC must require safe session pinning
+2. `P1`: deterministic 2PC phase timeouts
+3. `P1`: shared backend and shard config parsing
+4. `P1`: join execution coverage / early rejection alignment
+5. `P2`: expression and type semantic gaps
+6. `P2`: parser gaps around `SELECT ... INTO` and recursive CTE handling
+7. `P2`: CTE integration into the main `Session` path
+
+CTE work is explicitly held at `P2` for now.
+
+## First Execution Target
+
+The first implementation target is distributed 2PC safety. The current code explicitly allows an unpinned fallback path even though the same code comments state that this can silently corrupt pooled real-backend 2PC behavior. That is the highest-risk correctness issue and should fail closed.
+
+## Intended Change Shape
+
+- Extend the remote executor contract so executors can declare whether unpinned distributed 2PC fallback is safe
+- Keep pinned-session executors working as-is
+- Keep single-connection executors and selected mocks usable by explicit opt-in, not implicit fallback
+- Update distributed transaction and session tests to match the hardened contract
+
+## Non-Goals For This Pass
+
+- No attempt to solve all backlog items in one change
+- No large transaction subsystem rewrite
+- No CTE redesign in this phase