SamPlvs · SamPlvs · Jul 12, 2026
@@ -1220,10 +1220,33 @@ The `--no-headlines` flag is preserved (not removed) for backwards compatibility
 
 **Outcome:** +28 tests (826 → 854), green on Python 3.11 AND 3.12, ruff clean, validate-docs 0 failures; 12-check real-`uv run zo` smoke passed. Follow-up commit: `apply_bypass_overlay` no-ops when bypass is already active (inherit, not clobber), so `zo report --bypass-permissions` is safe alongside a model session in bypass — closes a lingering-bypass bug (model exits first → repo left in bypass). Docs: `docs/COMMANDS.md` + `README.md` gain `zo report` / `zo consolidate`. Branch `claude/zo-report-surrogate`, PR pending. PRIORS PR-045 added.
 
+---
+
 ## Decision: 2026-06-11T12:00:00Z
 **Type:** TESTING
 **Title:** CLI command-set test asserts subset, not equality — tolerate plugin-added commands
 **Decision:** `tests/unit/test_cli.py::TestCliGroup::test_cli_group_has_all_commands` now asserts `expected <= actual` (subset) instead of `expected == actual`, with a comment pointing at the `zo.commands` entry-point mechanism.
 **Rationale:** PR #99 shipped extension points whose documented purpose is letting downstream builds add CLI commands via entry points discovered at `zo.cli` import. A strict-equality command-set test makes the CORE suite fail in any environment where such a plugin is installed — the first real downstream plugin (registering a new command group) surfaced exactly that. The test's job is "core commands all present"; removals still fail under subset.
 **Alternatives considered:** (1) Computing `actual` minus plugin-contributed commands — `load_cli_plugins` doesn't record which commands each plugin added; tracking that adds machinery for a test. (2) Re-importing `zo.cli` with plugin discovery monkeypatched off — fragile import gymnastics for marginal benefit. (3) Leave it and tell downstream users to expect one red test — contradicts the extension point being a supported public mechanism.
 **Outcome:** Single-assertion diff + memory. 854 passed / 7 skipped on Python 3.11 AND 3.12, ruff clean, validate-docs 0 failures. Branch `claude/cli-test-plugin-tolerant`.
+
+---
+
+## Decision: 2026-07-12T14:30:00Z
+**Type:** ROADMAP + PLANNING
+**Title:** 2026-07 feature roadmap approved — four workstreams (lit review, cross-phase backedge, Slack bridge, VS Code extension); caveman dropped; build paused pre-implementation at Sam's request
+
+**Decision:** Plan of record: `memory/zo-platform/roadmaps/2026-07-feature-roadmap.md` (persisted verbatim at approval). Four sequenced workstreams, each a PR series:
+
+1. **WS1 — Phase 0 lit review, strengthened + opt-in for all modes.** New optional `## Literature Review` plan section (`LiteratureReviewSpec`, `## Experiment Loop` parser precedent); one enriched `literature_review_phase()` + `with_phase_0()` factory composed in `_resolve_phases()` (the PR #99 seam); four enforced gate artifacts under `research/` (existence-checked, gate ITERATEs naming missing files); `AGENT_PHASE_MAP` fix (add phase_0 to research-scout, REMOVE the accidental phase_0 from data-engineer, don't add code-reviewer); low-token keeps research-scout in phase_0 only; new `_prompt_research_context`. `zo.scholar` grounding layer stays a separate follow-up PR.
+2. **WS2 — `RETURN_TO_PHASE` backedge (F3 Phase A).** Per the session-028 design of record with ONE deviation: the requesting phase N goes **PENDING with M appended to `depends_on`**, NOT BLOCKED — BLOCKED means "human escalation required" (PR-037, `get_current_phase` contract); PENDING-with-deps-met resumes N automatically when M re-completes with zero consumer blast radius. Request channel = `.zo/revisit_request.json` written by the lead, centrally validated at BOTH real execution points (top of `advance_phase` AND `cli.build` between decompose and get_current_phase — `advance_phase` has no production caller today). Guardrails: global budget `--max-cross-phase-revisits` default 2 (persisted), Jaccard ≥0.9 duplicate-reason rejection (shared `text_similarity()` refactored from experiment_loop), structural validation, ESCALATE + evolution learning on rejection, budget visible in the lead prompt. New `## Revisits` STATE.md section (must be excluded from `_extract_extra_sections` or it duplicates on every save).
+3. **WS3 — Slack bridge, WhatsApp later.** Standalone `zo bridge` sidecar (PRD §8's sanctioned watcher pattern; survives across runs; answers "nothing running"), registered in the liveness registry with `role="bridge"` (peer-logic consumers must filter by role). Outbound: byte-offset tail of `logs/comms/*.jsonl` (dedup by file+offset — the `event_id` dedup in `_print_status` is a latent no-op, fix in passing), templated gate/error/digest/session messages. Inbound: allowlisted Slack users; `approve`/`reject <reason>` inject `/gates:approve`//`gates:reject` into the orchestrator pane via a new shared `src/zo/tmux_io.py` (extracted from wrapper.py:253-270/364-398); `mode` writes the hot-reloaded gate_mode file; free text relayed with provenance prefix. Surrogate lock files enriched with `tmux_pane_id`/`team_name`/`project`. Transport = Protocol; SlackTransport via official slack-sdk Socket Mode as optional extra `bridge = ["slack-sdk>=3.27"]`; empty allowlist = outbound-only.
+4. **WS4 — VS Code extension, design-first.** HTML mockups in `design/vscode/` are the approval artifact — Sam's sign-off gates all Stage-2 code. Engine: additive `--headless-tmux` (`tmux new-session -d` + `pipe-pane -o`) + new `src/zo/runtime.py` + versioned `.zo/runtime/session.json` contract; the session-028 "zero wrapper.py changes" claim was optimistic. Extension in monorepo `vscode/` dir (TypeScript, xterm.js, hand-rolled SVG charts, `zo runtime send` so ALL tmux logic stays in tested Python), documented extraction path to a `zo-vscode` repo once the contract freezes. v1 input model: read-only streams + composer (no per-keystroke TTY passthrough).
+
+**Sequencing:** D1 mockups → A1 → B1/B2 → C1–C3 → D2–D7. **Caveman: dropped from scope by Sam** ("No need for caveman now") — remains a roadmap card, nothing built, preset untouched.
+
+**Rationale:** Sam requested five features; scoping questions resolved lit-review shape (in-project Phase 0, not a standalone command), messaging order (Slack first — Socket Mode needs no public endpoint; WhatsApp needs Meta/Twilio + webhook hosting), VS Code approach (design mockups first), and scope (all five sequenced, then caveman dropped). Three exploration agents + three design agents grounded every workstream in verified file:line reality; the notable discovery is the phase_0 latent bug (runtime roster `[data-engineer]`, no required artifacts — the PR-004 prior about uninformed model design was structurally guaranteed by the code).
+
+**Alternatives considered:** standalone `zo research` mode (rejected by Sam); WhatsApp-first (heavier transport, deferred behind the Protocol); BLOCKED for the requesting phase per the session-028 sketch (rejected — breaks the PR-037 invariant and needs an auto-unblock side channel); per-gate `gate_decision` file for remote approval (rejected — duplicates the slash commands' STATE/DECISION_LOG/comms mutations; injection reuses one tested path); separate `zo-vscode` repo immediately (deferred — contract churn makes two repos a version-skew dance for one developer); bundling `zo.scholar` into PR A1 (rejected — different review profile, network seam, optional dep).
+
+**Outcome:** Roadmap persisted to tracked memory (see PR-046 — the session-028 internal plan file this pattern replaces was found to have vanished from `~/.claude/plans`). PR D1 (#103) executed end-to-end on branch `claude/vscode-design-mockups`: tokens.css + 9 pages generated by a 9-agent parallel workflow, then (after Sam's brief mid-session pause) a resumed consistency-review agent reconciled cross-page timeline/metric drift onto one canonical clock and browser-verified all pages in both themes; token-purity/skeleton/no-emoji/no-external-deps/link checks clean. Sam's initial reaction on viewing: "the screens are awesome!" — formal per-screen sign-off via the PR review of `00-overview.html` still gates Stage 2. Session numbering note: upstream PRs #101/#102 landed a session-039 mid-flight, so this session renumbered to 040 and the branch rebased onto updated main. Open style question deferred to Sam in the PR: em-dashes kept as the design-file house glyph despite the prose ban. Pickup: `sessions/session-040-2026-07-12.md`.
@@ -1399,3 +1399,27 @@ rm -f package-lock.json                            # keep the diff to the intend
 ### Verified Solution
 
 `_launch_and_monitor` gates `cleanup_stale_overlay` on `session_role == "model"` (report sessions never touch the overlay) and threads a `consolidate_on_exit` flag; `zo report --no-consolidate` sets it False. Tests: `test_report_session_never_cleans_overlay` (report never cleans even with no peer registered), `test_launch_and_monitor_no_consolidate_skips_merge`, plus the concurrency / conflict / resume / STATE-untouched suite (`test_surrogate_edge.py`). Concurrent **bypass** is handled by the same principle: `apply_bypass_overlay` no-ops when bypass is already active (inherit, not clobber), so a second bypass session (`zo report --bypass-permissions` alongside a model session in bypass) cannot leave the repo stuck in bypass after exit (`test_apply_is_noop_when_bypass_already_active`). **Cross-reference:** PR-037 (no session lock — single-session-by-design; this is the multi-session follow-on), PR-038 / PR-043 (permission-overlay lifecycle), PR-009 / PR-041 (built-must-be-wired — here, wired *and* made robust to the unupgraded peer).
+
+---
+
+## PR-046: Plans Referenced From Tracked Memory Must Themselves Be Tracked — ~/.claude/plans Is Ephemeral
+**Source:** Session 040 (2026-07-12), roadmap planning
+**Root cause category:** incomplete_rule (memory protocol covered STATE/DECISION_LOG/PRIORS but not externally-stored artifacts they reference)
+
+**Failure:** Session 028's STATE.md and DECISION_LOG both referenced "full internal plan at `~/.claude/plans/so-before-i-begin-peaceful-valley.md`" (effort estimates, file paths, TODO checklists for the F3 cross-phase work and the VS Code extension). In session 040 that file **no longer exists** — `~/.claude/plans/` is session tooling scratch, subject to cleanup outside ZO's control. Only the design-level summary duplicated into DECISION_LOG survived; the granular detail was unrecoverable and had to be re-derived from scratch (three exploration agents + three design agents).
+
+### Rules
+
+1. **Any artifact referenced from tracked memory must itself be tracked.** If STATE.md or DECISION_LOG says "full detail lives at <path>", that path must be inside the repo (for ZO-platform work: `memory/zo-platform/roadmaps/` or `sessions/`). Copy the artifact verbatim at reference time — at approval, not "later".
+   - **Why:** memory is only as durable as its weakest pointer. A tracked one-line reference to an untracked file silently becomes a dangling pointer, and the reader discovers it exactly when they need the detail.
+   - **How to apply:** when ending a session that produced an approved plan in `~/.claude/plans/`, `cp` it into `memory/zo-platform/roadmaps/<date>-<slug>.md` with a provenance header, and reference the tracked copy (the ephemeral path at most as a courtesy note).
+
+2. **Treat `~/.claude/plans/`, scratchpads, and session temp dirs as ephemeral by definition.** They are fine as working locations, never as archival ones. Same reasoning as PR-028 (gitignored project memory trapped on one machine — gitignored/external files don't transfer OR persist).
+
+3. **Duplication into DECISION_LOG is the safety net, not the archive.** The session-028 DECISION_LOG summary is what made re-derivation possible at all — keep writing rich summaries — but a summary is lossy by design; the full artifact needs its own tracked home.
+
+### Verified Solution
+
+The 2026-07 feature roadmap was persisted verbatim to `memory/zo-platform/roadmaps/2026-07-feature-roadmap.md` (with a provenance header) in the same session it was approved, and STATE.md/DECISION_LOG reference the tracked copy. Applied retroactively where possible: the lost session-028 detail was re-derived and is superseded by the new roadmap. The rule would have caught the original failure — session 028 would have copied the peaceful-valley file at write time.
+
+**Cross-reference:** PR-028 (project memory must live where it transfers), PR-003/PR-005 (references and rules drift without enforcement).