feat(v3.2): RPG-style architecture-first planning behind ATLAS_RPG_PLANNING (#120)

.env.example

@@ -51,6 +51,13 @@ ATLAS_CTX_SIZE=131072
 # leaves behavior unchanged. See docs/reports/CALL_GRAPH_REASONING_V3.md.
 # ATLAS_CALL_GRAPH=0
 
+# V3.2 RPG-style architecture-first planning (#120, EXPERIMENTAL, default off).
+# When 1/true, planning runs a two-stage Repository Planning Graph (modules ->
+# files -> signatures -> data-flow edges) ahead of problem-level PlanSearch, and
+# threads each node's planned interface into generation. Strictly additive — off
+# leaves planning/generation unchanged. See docs/reports/RPG_WAVELET_PLANNING_V3_2.md.
+# ATLAS_RPG_PLANNING=0
+
 # Host project directory bind-mounted to /workspace inside the proxy container.
 # This is the directory ATLAS reads and writes files in. The bind mount is
 # resolved at `docker compose up` time and is fixed for the container's

CHANGELOG.md

@@ -191,6 +191,31 @@
 
 ## [3.1.0] - 2026-05-12 — Maia
 
+### V3.2 — RPG-style architecture-first planning (#120, experimental, opt-in)
+- New `ATLAS_RPG_PLANNING` flag (default **off**) enables repository-level,
+  plan-then-fill planning ahead of the existing problem-level PlanSearch:
+  - **Wavelet substrate** (`v3-service/wavelet/`) — a faithful, dependency-free
+    Python port of [wavescope-mcp](https://github.com/yogthos/wavescope-mcp)
+    (Ricker CWT, structural signal, multi-resolution bands, project decomposition,
+    peak-diff). Numeric parity with upstream is golden-tested.
+  - **Repository Planning Graph** (`v3-service/rpg.py`, [arXiv:2509.16198](https://arxiv.org/abs/2509.16198)) —
+    two-stage construction (proposal capability tree → implementation files +
+    signatures + data-flow edges), graph validation/scoring, and a topological
+    projection to the existing flat `Plan` so the agent loop is unchanged. The
+    proposal stage is seeded with the wavelet coarse band on existing repos.
+  - **Graph-guided generation** — each node's planned interface (signatures,
+    edges) threads into its `/v3/generate` call (`proxy/rpg.go`), so the existing
+    PlanSearch ([arXiv:2409.03733](https://arxiv.org/abs/2409.03733)) fills a node
+    whose architecture is already pinned.
+  - **Structural verification + drift** — the candidate veto now rejects code
+    that doesn't realize its planned signatures; post-write drift detection
+    surfaces the affected downstream subgraph for re-planning.
+  - **Offline metrics** — `v3-service/rpg_eval.py` scores RPG artifacts for CI /
+    benchmark summaries.
+  - Strictly additive: with the flag off, planning and generation are unchanged.
+  - Design + phased status: `docs/reports/RPG_WAVELET_PLANNING_V3_2.md`. Credit
+    idea + framing to Dmitri Sotnikov (@yogthos), author of wavescope-mcp.
+
 ### Removed
 - Removed dead `ATLAS_USE_FOX` code paths in benchmark runner (#22)
 

atlas/cli/config_schema.py

@@ -46,6 +46,7 @@ class Field:
                               enum=("untrusted", "trusted", "fully-trusted")),
     "ATLAS_VERIFY_IN": Field("enum", enum=("sandbox", "host")),
     "ATLAS_CALL_GRAPH": Field("bool"),
+    "ATLAS_RPG_PLANNING": Field("bool"),
     "ATLAS_KEEP_LLAMA_WARM": Field("bool"),
     "ATLAS_FRESH_SLOT_PER_SESSION": Field("bool"),
     "ATLAS_DEDUP_READS": Field("bool"),

docker-compose.yml

@@ -146,6 +146,10 @@ services:
       # Structural call-graph reasoning (#39, experimental, default off). Read by
       # call_graph_enabled() inside this process, so it must be forwarded here.
       - ATLAS_CALL_GRAPH=${ATLAS_CALL_GRAPH:-0}
+      # V3.2 RPG-style planning (#120, experimental, default off). Read by
+      # rpg_planning_enabled() inside this process, so it must be forwarded
+      # here, not only to the proxy.
+      - ATLAS_RPG_PLANNING=${ATLAS_RPG_PLANNING:-0}
       # Plan-generation thinking mode (read inside this process — must be
       # forwarded here or setting it in .env has no effect).
       - ATLAS_PLAN_THINKING=${ATLAS_PLAN_THINKING:-}

docs/CONFIGURATION.md

@@ -457,6 +457,7 @@ Python FastAPI service for isolated code execution with compilation, linting, an
 | `ATLAS_SANDBOX_WORKSPACE_ROOT` | `/workspace` | The bind-mounted project root the executor confines `cwd` to. Container deployments keep the default; the E2E acceptance test overrides it to run the executor on the host under a temp dir. |
 | `ATLAS_SANDBOX_UID` / `ATLAS_SANDBOX_GID` | `1000` | Runtime uid/gid of the (non-root) sandbox container. `atlas init` writes the invoking user's ids so `/workspace` writes keep the right owner — the container drops all capabilities, so ownership must match. |
 | `ATLAS_PROXY_UID` / `ATLAS_PROXY_GID` | `1000` | Runtime uid/gid of the atlas-proxy container — same rationale as the sandbox ids: the proxy writes two host bind mounts (`/workspace` for file tools, `/data/lens_training` for lens sample banking), and the image's baked-in non-root user (uid 1001) can't write operator-owned dirs. `atlas init` writes the invoking user's ids. |
+| `ATLAS_RPG_PLANNING` | `0` | V3.2 RPG-style architecture-first planning (issue #120, EXPERIMENTAL). When on, `/v3/plan` builds a Repository Planning Graph (capabilities → files → signatures → data-flow edges) via the wavelet coarse band, plan steps carry per-node interface constraints into generation, drifted nodes get one corrective regeneration, and surviving drift is surfaced with the affected downstream subgraph. Off (default) leaves planning and generation byte-identical to the flat path. Read inside the v3-service container (forwarded by compose). See `docs/reports/RPG_WAVELET_PLANNING_V3_2.md`. |
 | `ATLAS_SANDBOX_CPUS` | `2` (compose fallback); `atlas init` writes ~75% of host cores | CPU quota for the sandbox container so a runaway build can't starve llama-server. The compose fallback is a conservative `2` so a raw `docker compose up` is never unlimited; `atlas init` writes ~75% of host cores (floor 1) — the recommended setting. `0` removes the cap (unlimited — not recommended). |
 | `ATLAS_SERVICE_TOKEN_FILE` | `/run/atlas-secrets/service-token` (containers) / `<root>/secrets/service-token` (host) | Path to the per-installation internal-auth token. Generated by `atlas init` (0600); mounted read-only into every Docker-Compose service. Present => all services require `Authorization: Bearer <token>` on non-health routes and clients inject it automatically. Absent => auth disabled (pre-token behavior; doctor warns). The K3s templates do not mount the token, so internal auth is disabled on K3s (doctor warns there too). Rotate with `atlas init --rotate-token` + `docker compose restart`. The token value itself never goes in `.env`, argv, or logs. |
 | `ATLAS_SECRETS_DIR` | `./secrets` | Host dir mounted read-only at `/run/atlas-secrets` in every service (holds `service-token`; the lens api-keys mount is separate). |