From cb981ad2c6f0582c2b35efdf9df45d61bc2ddb60 Mon Sep 17 00:00:00 2001
From: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
Date: Thu, 5 Feb 2026 22:45:55 -0500
Subject: [PATCH] docs: added FAQ section to v3_spec

---
 v3_spec.md | 835 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 747 insertions(+), 88 deletions(-)

diff --git a/v3_spec.md b/v3_spec.md
index 8ed8a744..fc052665 100644
--- a/v3_spec.md
+++ b/v3_spec.md
@@ -8,7 +8,7 @@ Key themes include:
 * **Actors** as a unifying abstraction (an LLM/agent *or* a whole graph).
 * A **sandbox + diff review** workflow and **CLI-first** interaction model.
 * A scalable **context/memory architecture** (hot/warm/cold tiers, per-actor views).
-* A future-facing correction model where the user can “edit the decision tree” and only recompute affected subtrees.
+* A future-facing correction model where the user can "edit the decision tree" and only recompute affected subtrees.
 
 # Big Picture: What CleverAgents v3 *is*
 
@@ -56,7 +56,7 @@ A plan always moves through the following phases, in order:
 
 **Action → Strategize → Execute → Apply → Applied (terminal)**
 
-Your draft uses “Strategy / Execution / Applied,” while the meeting notes use “Strategize / Execute / Apply.” In this spec:
+Your draft uses "Strategy / Execution / Applied," while the meeting notes use "Strategize / Execute / Apply." In this spec:
 
 * **Strategize** is the phase name (the output is a **strategy**).
 * **Execute** is the phase name (the output is an **execution result**).
@@ -77,11 +77,11 @@ Your draft proposes verbs that trigger phase transitions. v3 should standardize
 | Execute       | `apply`      | Applied    |
 
 **Important behavioral rule:**
-CleverAgents must support multiple “automation levels” that can automatically progress through these verbs without the user explicitly issuing them, but the verbs remain the conceptual contract.
+CleverAgents must support multiple "automation levels" that can automatically progress through these verbs without the user explicitly issuing them, but the verbs remain the conceptual contract.
 
 ### Plan States (Per Phase)
 
-A plan’s phase indicates “what step of the lifecycle it is in.” Separately, the plan has a **processing state** indicating “what is happening right now.”
+A plan's phase indicates "what step of the lifecycle it is in." Separately, the plan has a **processing state** indicating "what is happening right now."
 
 Recommended state model:
 
@@ -168,7 +168,7 @@ The way results are merged depends on the resource type:
 * **Other resources**: Pluggable merge strategies based on resource type
 * **Non-mergeable resources**: May require sequential execution only
 
-### The Plan “Decision Tree” and Visualization
+### The Plan "Decision Tree" and Visualization
 
 CleverAgents v3 intends to record enough information to render:
 
@@ -179,9 +179,9 @@ This implies each plan should persist:
 
 * decisions made,
 * the rationale (or at least the prompt/context snapshot that produced it),
-* dependencies (“this decision influenced these child plans”).
+* dependencies ("this decision influenced these child plans").
 
-This is required for “correcting plans” (see Behavior section).
+This is required for "correcting plans" (see Behavior section).
 
 
 ### Decision Data Model
@@ -507,7 +507,7 @@ Optional but recommended for reusable actions.
 
 #### 4) `definition_of_done` (DoD)
 
-Required. Must be explicit and testable. Prefer structured “must/should/may” language:
+Required. Must be explicit and testable. Prefer structured "must/should/may" language:
 
 * Must: requirements that must be met for completion
 * Should: quality targets
@@ -544,7 +544,7 @@ Actor abstraction is central: an actor may be a single agent or an entire graph.
 
 * Default: `false`.
 * If `true`: the plan must only use read-only skills and must never modify resources (even in sandbox).
-* Read-only actions are still useful for “investigation reports,” architecture reviews, or dry-run planning.
+* Read-only actions are still useful for "investigation reports," architecture reviews, or dry-run planning.
 
 #### 8) `inputs_schema` (recommended addition)
 
@@ -567,7 +567,7 @@ A policy bundle that can be applied to enforce safe execution:
 * require sandbox,
 * require human approval at Apply.
 
-This relates to the “checkpointable skills + sandbox” approach for safe writing.
+This relates to the "checkpointable skills + sandbox" approach for safe writing.
 
 ## Strategy (Strategize Phase)
 
@@ -619,7 +619,7 @@ Strategize is:
 * responsible for generating a strategy and subplan blueprint,
 * not allowed to execute subplans or modify resources.
 
-This “architect vs coder” separation is explicitly described as a core motivation.
+This "architect vs coder" separation is explicitly described as a core motivation.
 
 ### Strategize Data Model
 
@@ -629,7 +629,7 @@ A plan in Strategize contains all Action fields plus:
 
 A list of projects the plan is used on.
 
-Important: A strategy plan may target **multiple projects**. Multi-project work in one “window” is considered a major usability advantage over tools that require being run from a single directory.
+Important: A strategy plan may target **multiple projects**. Multi-project work in one "window" is considered a major usability advantage over tools that require being run from a single directory.
 
 #### 2) `strategy_context`
 
@@ -655,7 +655,7 @@ Recommended fields:
 The output plan:
 
 * steps (ordered and/or DAG),
-* conditions/branches (“if tests fail, do X”),
+* conditions/branches ("if tests fail, do X"),
 * subplans to spawn (including which action templates to use),
 * evaluation criteria (how to know success),
 * risk assessment.
@@ -711,7 +711,7 @@ Execute is where the plan actually performs work, but **in a sandboxed environme
 Key properties:
 
 1. **Work happens in a sandbox**
-   All file modifications, generated artifacts, and intermediate outputs live in an isolated “execution workspace” until Apply.
+   All file modifications, generated artifacts, and intermediate outputs live in an isolated "execution workspace" until Apply.
 
 2. **Execute may spawn subplans**
    Subplans are a first-class behavior of Execute: a parent plan can distribute work to child plans and merge results.
@@ -719,7 +719,7 @@ Key properties:
 3. **Execute must support checkpointing / rollback (when enabled)**
    Checkpointable skills allow rolling back to a checkpoint ID to recover from partial failure or wrong turns.
 
-4. **Execute produces a “reviewable diff”**
+4. **Execute produces a "reviewable diff"**
    Diff review sandbox is described as a differentiating feature: users can inspect changes before applying.
 
 ### Execution Workspace / Sandbox Model (Detailed)
@@ -855,9 +855,9 @@ A record of checkpoints:
 
 The meeting notes repeatedly emphasize the need for checkpoints tied to skills and rollbacks. The intended user-level behavior is:
 
-* “Give me a checkpoint ID.”
+* "Give me a checkpoint ID."
 * Perform additional operations.
-* “Roll back to checkpoint X.”
+* "Roll back to checkpoint X."
 
 Not all skills can support this; checkpointing must be declared per skill.
 
@@ -875,7 +875,7 @@ Examples:
 * Git skill: create commit or stash; rollback is reset/checkout
 * CLI skill inside a container: rollback by restoring filesystem snapshot or reloading base image state
 
-There’s explicit discussion that checkpointing is easier when skill scope is constrained (e.g., “only files within a docker image + git”).
+There's explicit discussion that checkpointing is easier when skill scope is constrained (e.g., "only files within a docker image + git").
 
 #### Plan-level rollback policy
 
@@ -894,7 +894,7 @@ Execution should be treated like a transactional pipeline:
   * commits a checkpoint on success, or
   * rolls back to the previous checkpoint on failure.
 
-This is explicitly motivated by “partial failure leaves codebase inconsistent” and the need for transaction rollback. 
+This is explicitly motivated by "partial failure leaves codebase inconsistent" and the need for transaction rollback. 
 
 ### Parsing and File Generation Expectations
 
@@ -914,23 +914,23 @@ Therefore, v3 should define a **standard output parsing pipeline**:
 5. If invalid, either:
 
    * request correction from actor, or
-   * quarantine the output as a “draft artifact” rather than writing it as real source.
+   * quarantine the output as a "draft artifact" rather than writing it as real source.
 
 ## Applied (Apply Phase)
 
 ### What Apply Does
 
-Apply takes the sandboxed work product and makes it “real” in the project.
+Apply takes the sandboxed work product and makes it "real" in the project.
 
 Core properties:
 
 1. **Apply is a controlled commit step**
-   Apply exists specifically to separate “generated work” from “committed work,” enabling review and safer automation.
+   Apply exists specifically to separate "generated work" from "committed work," enabling review and safer automation.
 
 2. **Apply is often the highest-risk step**
    It changes real systems. This is where permissions, approvals, and checks matter most.
 
-3. **Apply produces a terminal ‘applied’ plan**
+3. **Apply produces a terminal 'applied' plan**
    After successful apply, the plan becomes Applied.
 
 ### Apply Responsibilities (Recommended Checklist)
@@ -1002,7 +1002,7 @@ A plan in Apply includes:
 * `approval_record` (if human approvals are required)
 * `deployment_record` (optional, if apply triggers deploy)
 
-### “Applied” Terminal State
+### "Applied" Terminal State
 
 When Apply succeeds:
 
@@ -1120,7 +1120,7 @@ Project-level defaults:
 
 ### Multi-Project Operations
 
-A single plan may target multiple projects (e.g., updating shared schemas across services). This is considered a key UX advantage over “run in one directory” systems.
+A single plan may target multiple projects (e.g., updating shared schemas across services). This is considered a key UX advantage over "run in one directory" systems.
 
 In multi-project execution:
 
@@ -1356,7 +1356,7 @@ The transcript explicitly frames the graph nodes as being any of:
 * an MCP skill,
 * a custom tool node (arbitrary python code).
 
-This is a powerful simplification: “everything is a node.”
+This is a powerful simplification: "everything is a node."
 
 ## Agent
 
@@ -1387,7 +1387,7 @@ Agents should be configurable without code changes:
 * style constraints (verbosity, code style)
 * reliability controls (self-checks, validations)
 
-A design goal is user empowerment: “users customize LLM behavior without modifying core code.”
+A design goal is user empowerment: "users customize LLM behavior without modifying core code."
 
 ## Skills
 
@@ -1505,7 +1505,7 @@ This registry supports:
 
 ### What a Session Is
 
-A **session** is a user’s interactive thread with CleverAgents across time.
+A **session** is a user's interactive thread with CleverAgents across time.
 
 A session should:
 
@@ -1622,7 +1622,7 @@ A simple and powerful governance model:
 * Execute: writes occur but sandboxed → moderate restrictions
 * Apply: writes are real → strict restrictions + optional mandatory review
 
-This aligns with the four-phase model’s safety rationale.
+This aligns with the four-phase model's safety rationale.
 
 ## Resources
 
@@ -1697,7 +1697,7 @@ This enables:
 
 ## Context
 
-Context in v3 is not “dump all files into an LLM.” It is a system that:
+Context in v3 is not "dump all files into an LLM." It is a system that:
 
 * finds relevant information from resources,
 * injects appropriate subsets into each actor/node,
@@ -1709,7 +1709,7 @@ The transcript implies:
 
 * There is a global context concept,
 * But nodes only see what is injected into their prompts,
-* It’s functional but not yet elegant,
+* It's functional but not yet elegant,
 * A more advanced automated system is planned.
 
 ### Tiered Context Architecture (Hot/Warm/Cold)
@@ -1738,14 +1738,14 @@ A key missing feature identified in the notes is per-actor context views, filter
 The intended direction:
 
 * global context exists at plan level,
-* each actor gets a “view” of that context tuned to their role,
+* each actor gets a "view" of that context tuned to their role,
 * memory may be shared or per-plan depending on design choices.
 
 #### Actor Context View Service (Proposed)
 
 A dedicated module/service that:
 
-* maintains actor-specific “context views,”
+* maintains actor-specific "context views,"
 * tracks actor memory and relevance,
 * enforces actor-specific limits (tokens, file types, etc.).
 
@@ -1758,7 +1758,7 @@ A practical approach mentioned:
 
 This strongly suggests v3 should define:
 
-* an “initial context recipe” per project type (codebase vs documents vs infra),
+* an "initial context recipe" per project type (codebase vs documents vs infra),
 * iterative context refinement loops during strategize/execute.
 
 # Behavior
@@ -1840,7 +1840,7 @@ There is a note that validation logic is stubbed and must be implemented. The sp
 * validate rollback feasibility (if enabled)
 * validate project resource accessibility
 
-This prevents “plan runs with fake providers” and other surprises.
+This prevents "plan runs with fake providers" and other surprises.
 
 ### Cost / rate limits
 
@@ -1979,7 +1979,7 @@ This keeps history reproducible and prevents accidental destructive edits.
 
 ## Human-in-the-Loop Collaboration
 
-Even though the direction is “more autonomous,” the transcript explicitly recognizes that real workflows require engineers to collaborate with the system, editing code while it works, and using better UX integration (TUI/web/IDE).
+Even though the direction is "more autonomous," the transcript explicitly recognizes that real workflows require engineers to collaborate with the system, editing code while it works, and using better UX integration (TUI/web/IDE).
 
 So v3 should aim for:
 
@@ -1995,10 +1995,10 @@ So v3 should aim for:
 The system intends to be CLI-first, with:
 
 * a TUI built using Textual,
-* which can generate a web app “for free,”
+* which can generate a web app "for free,"
 * and later an IDE plugin that embeds the TUI in the IDE.
 
-This implies a “single UI codebase” model:
+This implies a "single UI codebase" model:
 
 * same underlying view logic,
 * multiple frontends.
@@ -2073,13 +2073,13 @@ If you want, I can also produce:
 
 This section describes—**exhaustively and in implementation terms**—what remains to be done to bring the current CleverAgents codebase up to the intended CleverAgents v3 behavior described in the transcript/meeting notes (Action → Strategize → Execute → Apply; actors as composable graphs; sandbox + diff review; context scaling; checkpointable skills; etc.). 
 
-It is based primarily on the attached “what’s missing / code analysis” document (last updated **Jan 29, 2026**) which outlines the current master branch’s functional gaps, architectural limitations, and regressions introduced by new reactive/langgraph code. 
+It is based primarily on the attached "what's missing / code analysis" document (last updated **Jan 29, 2026**) which outlines the current master branch's functional gaps, architectural limitations, and regressions introduced by new reactive/langgraph code. 
 
 ---
 
 ## Current State vs Intended v3: The Gap in One Sentence
 
-Right now, the codebase still behaves like a **linear, single-file “LLM dump to generated.py” pipeline** (with tiny context and stubbed validation), while intended v3 requires a **plan lifecycle engine that can reliably generate, validate, sandbox, diff-review, and apply multi-file/multi-project changes—backed by checkpointable skills, rich context, and composable actor graphs**.
+Right now, the codebase still behaves like a **linear, single-file "LLM dump to generated.py" pipeline** (with tiny context and stubbed validation), while intended v3 requires a **plan lifecycle engine that can reliably generate, validate, sandbox, diff-review, and apply multi-file/multi-project changes—backed by checkpointable skills, rich context, and composable actor graphs**.
 
 Everything below is the concrete work required to close that gap.
 
@@ -2089,9 +2089,9 @@ Everything below is the concrete work required to close that gap.
 
 ### Problem (today)
 
-Per the code analysis, the current plan generation workflow is **hard-coded to emit exactly one `Change`** and write one file containing **raw LLM output** (often including markdown + explanations). This alone prevents “repo writing,” multi-service changes, scaffolding, and most realistic coding tasks. 
+Per the code analysis, the current plan generation workflow is **hard-coded to emit exactly one `Change`** and write one file containing **raw LLM output** (often including markdown + explanations). This alone prevents "repo writing," multi-service changes, scaffolding, and most realistic coding tasks. 
 
-### What “done” looks like
+### What "done" looks like
 
 The system must be able to produce **N changes** across **N files**, where each change is one of:
 
@@ -2104,7 +2104,7 @@ The system must be able to produce **N changes** across **N files**, where each
 
 ### High-level implementation plan
 
-#### A. Upgrade the internal “change set” model (do this first)
+#### A. Upgrade the internal "change set" model (do this first)
 
 Create a canonical internal representation for generated output, e.g.:
 
@@ -2125,11 +2125,11 @@ Where `Change` includes:
 * `patch` (optional unified diff)
 * `language` (optional but helpful for validation)
 
-**Key requirement:** the pipeline must stop treating a plan as “one output string”; it must treat the plan as “a structured set of file ops.”
+**Key requirement:** the pipeline must stop treating a plan as "one output string"; it must treat the plan as "a structured set of file ops."
 
 #### B. Force a structured LLM output contract (JSON-first)
 
-To get multi-file reliably, require the execution actor (or a dedicated “renderer” actor) to output **strict JSON** that conforms to a schema, for example:
+To get multi-file reliably, require the execution actor (or a dedicated "renderer" actor) to output **strict JSON** that conforms to a schema, for example:
 
 ```json
 {
@@ -2147,12 +2147,12 @@ Implementation details:
 * Define a JSON schema (or Pydantic model) and validate strictly.
 * If invalid JSON:
 
-  * run an automatic “repair” step (LLM or deterministic fixer),
-  * if still invalid, fail the phase with a clear error and keep artifacts for review (don’t write junk into files).
+  * run an automatic "repair" step (LLM or deterministic fixer),
+  * if still invalid, fail the phase with a clear error and keep artifacts for review (don't write junk into files).
 
-**Why JSON-first matters:** the current “strip only the outer fences” behavior is not enough and will always regress into “explanations in code.” 
+**Why JSON-first matters:** the current "strip only the outer fences" behavior is not enough and will always regress into "explanations in code." 
 
-#### C. Provide a fallback parser (markdown/code-fence tolerant) but never “raw dump”
+#### C. Provide a fallback parser (markdown/code-fence tolerant) but never "raw dump"
 
 Even with JSON-first, a fallback parser is practical. But the fallback must produce the same `ChangeSet` structure.
 
@@ -2174,9 +2174,9 @@ Once you can create multiple files, you need deterministic rules for directories
 
 * auto-create directories for new files (safe, idempotent)
 * enforce project root boundaries (never escape the repo root)
-* enforce ignore patterns / deny lists (e.g., don’t create inside `.git/`)
+* enforce ignore patterns / deny lists (e.g., don't create inside `.git/`)
 
-This directly addresses the “create REST API” expectation (routes/, models/, etc.) that current code cannot meet. 
+This directly addresses the "create REST API" expectation (routes/, models/, etc.) that current code cannot meet. 
 
 ---
 
@@ -2186,9 +2186,9 @@ This directly addresses the “create REST API” expectation (routes/, models/,
 
 The Jan 29 update introduced substantial new code under `src/cleveragents/langgraph/` and `src/cleveragents/reactive/` (graphs, nodes, state, RxPy routing), but the analysis states it is **not connected to the main plan generation workflow** and therefore does not fix the fundamental functional issues. 
 
-### What “done” looks like
+### What "done" looks like
 
-* A plan’s Strategize and Execute phases run through a real graph engine (LangGraph-like execution).
+* A plan's Strategize and Execute phases run through a real graph engine (LangGraph-like execution).
 * The graph actually drives:
 
   * context selection,
@@ -2201,7 +2201,7 @@ The Jan 29 update introduced substantial new code under `src/cleveragents/langgr
 
 ### High-level implementation plan
 
-#### A. Create a single “PlanLifecycleGraph” entrypoint
+#### A. Create a single "PlanLifecycleGraph" entrypoint
 
 Define a top-level orchestrator graph per plan instance:
 
@@ -2209,7 +2209,7 @@ Define a top-level orchestrator graph per plan instance:
 
 * gather context (read-only)
 * produce strategy (machine-usable blueprint + narrative)
-* produce an “execution plan” (tasks/subplans)
+* produce an "execution plan" (tasks/subplans)
 
 **Execute subgraph**
 
@@ -2224,7 +2224,7 @@ Define a top-level orchestrator graph per plan instance:
 * apply changes transactionally
 * record audit log + final state
 
-#### B. Replace (or wrap) the current “tell/build/apply/file” pipeline
+#### B. Replace (or wrap) the current "tell/build/apply/file" pipeline
 
 Maintain backward compatibility at the CLI layer (for now), but internally:
 
@@ -2232,17 +2232,17 @@ Maintain backward compatibility at the CLI layer (for now), but internally:
 * `build` maps to Strategize + Execute
 * `apply` maps to Apply
 
-The key is to stop having “build” be “one LLM call that returns one file.”
+The key is to stop having "build" be "one LLM call that returns one file."
 
 #### C. Make the new reactive routing optional—not mandatory
 
-The reactive router (RxPy streams) is powerful, but don’t make it the required execution substrate until it’s stable and secure (see security section below). Use it as:
+The reactive router (RxPy streams) is powerful, but don't make it the required execution substrate until it's stable and secure (see security section below). Use it as:
 
 * an experimental routing layer,
 * or a message bus,
 * or a future optimization for streaming UX.
 
-But the “plan must work” path should be stable with deterministic orchestration.
+But the "plan must work" path should be stable with deterministic orchestration.
 
 ---
 
@@ -2252,7 +2252,7 @@ But the “plan must work” path should be stable with deterministic orchestrat
 
 The analysis notes that apply currently writes files directly and can leave the codebase inconsistent on partial failures; diff preview is missing or insufficient; rollback is not robust. 
 
-### What “done” looks like (v3 expectation)
+### What "done" looks like (v3 expectation)
 
 * Execute never mutates the real project directly.
 * All changes happen in a sandbox.
@@ -2301,19 +2301,19 @@ A plan should store:
 * file list changed
 * per-file diff
 * summary (what changed + why)
-* “risk markers” (e.g., touched auth code, migrations, infra)
+* "risk markers" (e.g., touched auth code, migrations, infra)
 
 This is a core differentiator and must be polished because it is the human safety boundary. 
 
 ---
 
-## 4) Build the “Checkpointable Skills” Layer (Hard Blocker for Reliable Autonomy)
+## 4) Build the "Checkpointable Skills" Layer (Hard Blocker for Reliable Autonomy)
 
 ### Problem (today)
 
 The system lacks robust rollback, and the analysis emphasizes the need for checkpoints to avoid partial failures and inconsistent states. The meeting notes also highlight the intent to build checkpointable skills because MCP metadata is insufficient for write scope and rollback guarantees.
 
-### What “done” looks like
+### What "done" looks like
 
 * Skills declare whether they are checkpointable.
 * The execution engine can:
@@ -2332,12 +2332,12 @@ Every skill should optionally support:
 * `rollback(checkpoint_id) -> None`
 * `describe_effects(call) -> ResourceEffects` (what it read/wrote)
 
-Not every skill can implement rollback. But for “write” skills you rely on, you need either:
+Not every skill can implement rollback. But for "write" skills you rely on, you need either:
 
 * skill-level rollback, or
 * containment (sandbox) + external rollback (git reset, snapshot restore).
 
-#### B. Implement checkpointable “core skills” first
+#### B. Implement checkpointable "core skills" first
 
 Start with:
 
@@ -2357,11 +2357,11 @@ The system needs to know:
 * checkpointability
 * side effects
 
-The meeting notes explicitly call out that MCP doesn’t provide enough writing-scope metadata for safe automation; v3 needs an internal extension/registry. 
+The meeting notes explicitly call out that MCP doesn't provide enough writing-scope metadata for safe automation; v3 needs an internal extension/registry. 
 
 ---
 
-## 5) Expand Context Beyond “300 chars × 5 files” and Make It Actor-Aware (Hard Blocker for Real Code Understanding)
+## 5) Expand Context Beyond "300 chars × 5 files" and Make It Actor-Aware (Hard Blocker for Real Code Understanding)
 
 ### Problem (today)
 
@@ -2371,7 +2371,7 @@ The analysis states the context system is effectively a placeholder:
 * no robust repo understanding,
 * inadequate for realistic tasks. 
 
-### What “done” looks like
+### What "done" looks like
 
 * The system can ingest and reason over large repos via indexing and retrieval.
 * Context is not a single global blob; it is **assembled per actor/node** based on role and task.
@@ -2398,7 +2398,7 @@ As described in the meeting notes:
 
 Then implement automatic promote/demote.
 
-#### C. Add “Actor Context Views”
+#### C. Add "Actor Context Views"
 
 Actors require tailored views:
 
@@ -2421,7 +2421,7 @@ The analysis identifies multiple provider-level failures:
 * hardcoding auto-debug to OpenAI GPT-4 regardless of configuration,
 * OpenRouter listed but not implemented. 
 
-### What “done” looks like
+### What "done" looks like
 
 * If no provider is configured, the user gets a clear, actionable error.
 * Auto-debug uses the configured actor/provider.
@@ -2432,7 +2432,7 @@ The analysis identifies multiple provider-level failures:
 #### A. Remove FakeListLLM as default behavior
 
 * Keep FakeListLLM **only** for tests.
-* In production, enforce: “no provider configured → fail fast with clear message.”
+* In production, enforce: "no provider configured → fail fast with clear message."
 
 #### B. Make provider selection actor-driven end-to-end
 
@@ -2447,7 +2447,7 @@ Auto-debug should be:
 
 * a plan/action using an actor, not a hard-coded special-case.
 
-#### C. Implement “provider auto-support” strategy
+#### C. Implement "provider auto-support" strategy
 
 To avoid manual churn:
 
@@ -2460,9 +2460,9 @@ To avoid manual churn:
 
 ### Problem (today)
 
-Validation is currently a stub (“PASS” or output length > 10). This guarantees that broken outputs will be considered valid. 
+Validation is currently a stub ("PASS" or output length > 10). This guarantees that broken outputs will be considered valid. 
 
-### What “done” looks like
+### What "done" looks like
 
 Validation in Execute must include:
 
@@ -2495,7 +2495,7 @@ Then enforce:
 
 * Execute phase cannot complete if validation fails (unless user overrides explicitly).
 
-Also fix the “invalid python docstring wrap” behavior:
+Also fix the "invalid python docstring wrap" behavior:
 
 * invalid output should trigger a repair loop or be quarantined as an artifact,
 * not silently converted into useless code. 
@@ -2513,7 +2513,7 @@ The analysis calls out:
 * no resume/progress persistence,
 * missing cleanup for abandoned plans. 
 
-### What “done” looks like
+### What "done" looks like
 
 * Plans can be resumed after interruption.
 * Plan execution is locked per project/sandbox to avoid races.
@@ -2526,7 +2526,7 @@ The analysis calls out:
 * Persist step-level progress events.
 * Implement resumable execution by checkpoint:
 
-  * “resume from checkpoint X” or “resume from step Y”
+  * "resume from checkpoint X" or "resume from step Y"
 * Add lifecycle cleanup jobs:
 
   * garbage collect old sandboxes
@@ -2545,7 +2545,7 @@ The analysis reports a **critical `eval()` vulnerability** in stream routing con
 * thread safety issues,
 * template injection risks. 
 
-### What “done” looks like
+### What "done" looks like
 
 * No configuration-driven arbitrary code execution (no eval).
 * Errors are surfaced, not swallowed.
@@ -2560,7 +2560,7 @@ Replace with one of:
 
 * a whitelist of allowed transform operators
 * a small safe expression language (parsed, not executed)
-* “transform” must reference a named function from a registry, not arbitrary text
+* "transform" must reference a named function from a registry, not arbitrary text
 
 #### B. Stop swallowing exceptions
 
@@ -2582,13 +2582,13 @@ If templating is needed, use a sandboxed template engine or restrict tokens seve
 
 ---
 
-## 10) Finish the “Plan System” (Actions, Strategize, Execute, Apply) in Storage + CLI + UI
+## 10) Finish the "Plan System" (Actions, Strategize, Execute, Apply) in Storage + CLI + UI
 
 ### Problem (today)
 
 The analysis describes the current master as still conceptually the linear tell/build/apply pipeline. Meanwhile, intended v3 introduces reusable Actions decoupled from Projects, and separate Strategize/Execute/Apply phases with automation levels.
 
-### What “done” looks like
+### What "done" looks like
 
 * Actions exist as reusable templates.
 * Using an Action creates a plan in Strategize.
@@ -2641,7 +2641,7 @@ Meeting notes and analysis agree that actor CRUD exists or is being ported, but
 * no per-actor memory,
 * no actor-defined orchestration behavior in practice.
 
-### What “done” looks like
+### What "done" looks like
 
 An actor should be able to define:
 
@@ -2683,7 +2683,7 @@ The analysis lists:
 * Require migrations to exist and be applied (Alembic).
 * Remove global registry singletons; make DI container own state.
 * Make session memory persistent by default (SQLite is acceptable).
-* Store session IDs in DB; never “generate and forget.”
+* Store session IDs in DB; never "generate and forget."
 
 ---
 
@@ -2732,11 +2732,11 @@ The meeting notes say multi-user prompt injection and governance are less releva
 
   * treat user input as data, not instruction overrides
   * strict templating and role separation
-* Separate “execution happens locally” from “coordination happens on server” (optional architecture).
+* Separate "execution happens locally" from "coordination happens on server" (optional architecture).
 
 ---
 
-## Suggested Build Order (So You Don’t Get Stuck)
+## Suggested Build Order (So You Don't Get Stuck)
 
 If you want a pragmatic sequencing that preserves momentum and prevents rewrites:
 
@@ -2751,13 +2751,13 @@ If you want a pragmatic sequencing that preserves momentum and prevents rewrites
 9. **TUI plan tree + correction UX**
 10. **Cost controls + server-mode foundations**
 
-This ordering matches the reality that without multi-file output and safe apply, higher-level orchestration and context improvements won’t matter—the system still can’t “do the work” safely.
+This ordering matches the reality that without multi-file output and safe apply, higher-level orchestration and context improvements won't matter—the system still can't "do the work" safely.
 
 ---
 
-## Acceptance Criteria for “Fully Functional” (Concrete)
+## Acceptance Criteria for "Fully Functional" (Concrete)
 
-A realistic “fully functional” bar (aligned to intended v3 behavior) is:
+A realistic "fully functional" bar (aligned to intended v3 behavior) is:
 
 * Can **strategize** read-only using real context across many files.
 * Can **execute** in sandbox, producing a multi-file ChangeSet for non-trivial features.
@@ -2770,3 +2770,662 @@ A realistic “fully functional” bar (aligned to intended v3 behavior) is:
 * Has persistent session/memory so iterative CLI use works.
 
 Everything listed earlier maps directly to closing the gaps documented in the attached analysis and to achieving the behaviors described in the transcript.
+
+# CleverAgents v3 Architecture FAQ
+
+## Q: How does CleverAgents v3 handle persistent repository knowledge beyond ephemeral context windows?
+
+**What exists today architecturally**: The v3 specification defines a sophisticated multi-tier memory system that goes far beyond ephemeral context windows. At its core is the Decision Tree structure (lines 187-426) which provides a durable, queryable record of every choice made during planning, along with the complete context that informed those choices.
+
+**How the persistent model works in practice**:
+
+When a strategy actor analyzes a codebase during the Strategize phase, it doesn't just make decisions in isolation. Each decision creates a comprehensive Decision record that includes:
+
+```yaml
+context_snapshot:
+  hot_context_hash: str              # Cryptographic hash of the exact context
+  hot_context_ref: str               # Pointer to the full stored snapshot
+  relevant_resources: list[ResourceRef]  # Every file/symbol that influenced this decision
+  actor_state_ref: str               # Complete LangGraph checkpoint
+```
+
+This means when the system decides "refactor the authentication module to use async patterns," it permanently records:
+- Which files were examined to make that decision
+- What symbols and dependencies were traced
+- The exact code state that was analyzed
+- The reasoning chain that led to this choice
+- Alternative approaches that were considered but rejected
+
+**The three-tier memory architecture enables scale**:
+
+1. **Hot tier**: Immediate working context (what's in the current LLM context window)
+2. **Warm tier**: Recent decisions and their contexts from this plan tree - quickly accessible
+3. **Cold tier**: Historical decisions from past plans on this codebase - queryable but not in active memory
+
+When working on a 50,000 file codebase, the system doesn't need to hold all files in memory. Instead:
+- Hot context focuses on the immediate task (e.g., 10-20 files for a specific refactoring)
+- Warm context maintains the decision chain that got us here
+- Cold context provides historical patterns ("last time we refactored auth, we also had to update these services")
+
+**Why this scales to massive codebases**:
+
+The key insight is that software development is inherently local - even in huge codebases, individual changes typically touch a bounded set of files. The Decision Tree captures these localities. When converting Firefox to Rust (your example), the system would:
+
+1. Make high-level architectural decisions (captured as root decision nodes)
+2. Decompose into major subsystem conversions (each a decision spawning subplans)
+3. Each subsystem plan makes decisions about its modules
+4. Module plans make decisions about individual files
+
+At each level, only the relevant context is loaded. The persistent decision graph means we can always reconstruct why we're converting a particular module and what constraints apply from higher-level decisions.
+
+**Concrete example of persistence in action**:
+
+```
+Plan: Convert Firefox Renderer to Rust
+├── [Decision] Architecture approach: Start with leaf modules, work inward
+│   Context: Analyzed module dependency graph, 2,847 modules total
+│   Resources: module_graph.json, architecture_docs.md
+│   
+├── [Decision] Phase 1: Convert utility libraries (no external deps)
+│   └── [Subplan] Convert string_utils module
+│       ├── [Decision] Use Rust's String type, not custom implementation
+│       │   Context: Analyzed 47 string_utils.cpp functions
+│       │   Resources: string_utils.cpp, string_utils.h, 12 dependent files
+│       │   Rationale: Rust's String provides same guarantees with better ergonomics
+```
+
+Even months later, we can query: "Why did we use Rust's String type?" and get the exact context and reasoning, without reprocessing the entire codebase.
+
+## Q: How does the system compute task-specific dependency closures for large-scale operations?
+
+**What exists today architecturally**: The v3 specification defines multiple mechanisms for computing and maintaining minimal dependency closures. The execution blueprint (line 671) produced during the Strategize phase doesn't just list steps - it includes a complete dependency graph with explicit scoping for each operation.
+
+**How dependency closure computation works**:
+
+During the Strategize phase, the strategy actor employs several mechanisms to compute precise dependency closures:
+
+1. **Resource-aware analysis**: The actor uses specialized skills to trace dependencies:
+   ```python
+   # Pseudocode of what happens inside a strategy actor
+   def compute_closure_for_refactoring(target_module):
+       closure = ResourceClosure()
+       
+       # Direct file dependencies
+       closure.add_files(find_imports(target_module))
+       closure.add_files(find_includes(target_module))
+       
+       # Symbol dependencies
+       for symbol in extract_exported_symbols(target_module):
+           closure.add_files(find_symbol_usage(symbol, scope='project'))
+       
+       # Test dependencies
+       closure.add_files(find_tests_for_module(target_module))
+       
+       # Build system dependencies
+       closure.add_files(find_build_references(target_module))
+       
+       return closure
+   ```
+
+2. **Hierarchical scoping**: When spawning subplans (lines 127-170), each subplan receives:
+   - An explicit `relevant_resources` list
+   - A `sandbox_strategy` appropriate for those resources
+   - Clear boundaries of what it can and cannot modify
+
+3. **Decision-based tracking**: Each `subplan_spawn` decision records:
+   ```yaml
+   decision_type: subplan_spawn
+   chosen_option: "Refactor authentication module"
+   downstream_plan_ids: ["plan-auth-refactor-123"]
+   artifacts_produced: 
+     - auth_module_files: ["auth.rs", "auth_test.rs", "auth_types.rs"]
+     - api_updates: ["api/v2/login.rs", "api/v2/logout.rs"]
+   ```
+
+**Concrete example - Converting a subsystem to Rust**:
+
+Let's trace how the system handles "Convert Firefox's Network Stack to Rust":
+
+```
+STRATEGIZE PHASE:
+1. Analyze network stack structure
+   - Identifies 847 C++ files in netwerk/ directory
+   - Traces public API surface (237 exported functions)
+   - Maps internal dependencies (1,432 internal calls)
+   
+2. Compute minimal closure for Phase 1 (DNS resolver):
+   - Core files: dns_resolver.cpp, dns_cache.cpp, dns_config.cpp (3 files)
+   - Direct dependencies: 12 files in netwerk/base/
+   - Test files: 8 test files specific to DNS
+   - Build files: 2 moz.build files
+   - Total closure: 25 files (not 847!)
+   
+3. Generate execution blueprint with subplans:
+   - convert-dns-types: Closure of 5 files (type definitions)
+   - convert-dns-cache: Closure of 8 files (cache + tests)  
+   - convert-dns-resolver: Closure of 12 files (resolver + integration)
+```
+
+**Why this is tractable even for massive codebases**:
+
+The system leverages several key insights about real software:
+
+1. **Modular boundaries exist**: Even in legacy codebases, there are natural boundaries
+2. **Changes are incremental**: We don't convert 50,000 files atomically
+3. **Dependencies are sparse**: Most modules depend on a small fraction of the codebase
+4. **Interfaces are narrow**: Public APIs are much smaller than implementations
+
+The Firefox example would decompose into ~1,000 bounded subplans, each touching 10-100 files. The parent plan tracks the overall architecture, while each subplan maintains its focused closure.
+
+**How we prevent closure explosion**:
+
+- **Lazy expansion**: Dependencies are traced only as deep as needed for correctness
+- **Interface-based boundaries**: When possible, work against stable interfaces
+- **Incremental validation**: Each subplan validates its changes don't break dependents
+- **Hierarchical merge strategies**: Parent plans resolve conflicts between subplan changes
+
+## Q: What mechanisms enforce global consistency during parallel execution across many files?
+
+**What exists today architecturally**: The sandbox model (lines 723-817) combined with hierarchical plan execution provides strong guarantees about consistency during parallel execution. This isn't just process isolation - it's semantic isolation with intelligent merge strategies.
+
+**How the coordination mechanism prevents compound errors**:
+
+1. **Complete isolation during execution**:
+   Each plan executes in its own sandbox, which means:
+   ```
+   Plan A (refactoring auth module):
+   - Sandbox A1: Contains only auth/*.cpp, auth_tests/*.cpp
+   - Cannot see Plan B's intermediate states
+   - Cannot accidentally depend on Plan B's half-done work
+   
+   Plan B (updating API endpoints):
+   - Sandbox B1: Contains only api/*.cpp, api_tests/*.cpp  
+   - Makes changes assuming current auth interface
+   - Protected from Plan A's intermediate refactoring
+   ```
+
+2. **Resource-specific sandbox strategies provide natural coordination**:
+   ```yaml
+   Git repositories:
+     - Strategy: git worktrees
+     - Coordination: Git's three-way merge algorithm
+     - Conflict detection: Built into Git
+     - Rollback: git reset/checkout
+   
+   Databases:
+     - Strategy: Transaction isolation  
+     - Coordination: MVCC (multi-version concurrency control)
+     - Conflict detection: Serialization failures
+     - Rollback: Transaction abort
+   
+   Cloud Infrastructure:
+     - Strategy: Terraform workspaces
+     - Coordination: State locking
+     - Conflict detection: Resource conflicts in plan
+     - Rollback: Previous state restoration
+   ```
+
+3. **Hierarchical merge resolution**:
+   When subplans complete, the parent plan performs intelligent merging:
+   ```python
+   def merge_subplan_results(subplan_results):
+       # Group by resource type
+       by_resource = group_by_resource_type(subplan_results)
+       
+       # Apply resource-specific merge strategies
+       for resource_type, changes in by_resource:
+           if resource_type == 'git_repo':
+               merge_git_changes(changes)  # Three-way merge
+           elif resource_type == 'database':
+               merge_db_changes(changes)   # Sequential application
+           elif resource_type == 'config_files':
+               merge_config_changes(changes)  # Smart JSON/YAML merge
+       
+       # Validate merged state
+       run_integration_tests()
+   ```
+
+**Concrete example - Preventing cascading failures**:
+
+Consider refactoring a shared authentication library used by 15 services:
+
+```
+PARALLEL EXECUTION WITHOUT COORDINATION (what we prevent):
+- Service A refactors to async auth → breaks Service B
+- Service B compensates with workaround → breaks Service C  
+- Service C changes error handling → breaks Services D, E, F
+- Cascade of failures!
+
+CLEVERAGENTS V3 COORDINATED EXECUTION:
+Parent Plan: Refactor auth library
+├── Subplan 1: Update auth library interface
+│   Sandbox: Only auth library files
+│   Output: New interface definition
+│   
+├── Barrier: Wait for Subplan 1 completion
+│   
+├── Parallel Subplans 2-16: Update each service
+│   Each sandbox: Only that service's files
+│   Each uses: New interface from Subplan 1
+│   No inter-service dependencies during execution
+│   
+└── Merge Phase:
+    - Collect all service updates
+    - Apply to main branch in order
+    - Run integration tests
+    - If conflicts: Parent plan resolves using semantic understanding
+```
+
+**Advanced coordination patterns**:
+
+1. **Optimistic concurrency with semantic conflict resolution**:
+   ```yaml
+   Two subplans both modify api/user.rs:
+   - Plan A: Adds async fn get_user_profile()
+   - Plan B: Adds fn validate_user_permissions()
+   
+   Merge strategy:
+   - Git merge succeeds (different functions)
+   - Semantic validation ensures both functions work together
+   - Parent plan adds integration glue if needed
+   ```
+
+2. **Checkpoint-based coordination**:
+   ```
+   Execution timeline:
+   T1: Subplan A creates checkpoint before major refactor
+   T2: Subplan B creates checkpoint before API changes
+   T3: Subplan A encounters error, rolls back to T1
+   T4: Subplan B completes successfully
+   T5: Subplan A retries with knowledge of B's success
+   ```
+
+3. **Resource locking for critical sections**:
+   ```yaml
+   When modifying shared schema files:
+   - Acquire exclusive lock on schema resources
+   - Make changes atomically
+   - Release lock with new version
+   - Other plans rebase on new schema
+   ```
+
+## Q: How does the system proactively prevent semantic errors before they propagate?
+
+**What exists today architecturally**: The v3 specification defines multiple layers of proactive error prevention that go far beyond traditional testing. This is a comprehensive defense-in-depth approach that catches semantic errors before they can propagate.
+
+**Layer 1: Decision-time validation during Strategize**:
+
+Every decision includes semantic validation:
+```yaml
+Decision: Refactor payment module to async
+alternatives_considered:
+  - "Convert to async/await patterns" (chosen)
+  - "Use thread pool with channels" (rejected: doesn't integrate with async ecosystem)
+  - "Keep synchronous with timeout" (rejected: doesn't solve core latency issue)
+confidence_score: 0.85
+validation_performed:
+  - Checked all payment API consumers can handle async
+  - Verified database driver supports async operations
+  - Confirmed no regulatory requirement for sync processing
+```
+
+**Layer 2: Execution-time semantic guards**:
+
+The execution actor configuration includes validation nodes that understand semantics:
+
+```yaml
+actors:
+  code_executor:
+    type: graph
+    nodes:
+      - name: semantic_validator
+        type: tool
+        config:
+          tools:
+            - name: validate_api_compatibility
+              code: |
+                # Not just syntax checking - semantic validation
+                old_api = extract_api_signature(previous_version)
+                new_api = extract_api_signature(current_version)
+                
+                breaking_changes = find_breaking_changes(old_api, new_api)
+                if breaking_changes:
+                    # Don't just fail - understand the impact
+                    affected_consumers = find_api_consumers(breaking_changes)
+                    migration_plan = generate_migration(breaking_changes)
+                    
+                    if can_auto_migrate(affected_consumers, migration_plan):
+                        apply_migration(migration_plan)
+                    else:
+                        raise SemanticError(
+                            "Breaking API changes require manual review",
+                            changes=breaking_changes,
+                            affected=affected_consumers
+                        )
+```
+
+**Layer 3: Invariant enforcement through the type system**:
+
+```python
+# The system maintains semantic invariants
+class RefactoringInvariants:
+    # User-defined invariants for the codebase
+    invariants = [
+        "All public APIs must maintain backward compatibility",
+        "Database transactions must complete within 5 seconds",
+        "Authentication must always use OAuth2",
+        "Payment processing must be idempotent"
+    ]
+    
+    def check_invariant_preservation(self, changes):
+        for invariant in self.invariants:
+            if not self.verify_invariant(invariant, changes):
+                return InvariantViolation(invariant, changes)
+        return Success()
+```
+
+**Layer 4: Predictive error prevention through pattern matching**:
+
+The system learns from past failures:
+```yaml
+Error Pattern Database:
+  - pattern: "Async conversion in payment module"
+    historical_failures:
+      - "Race condition in payment confirmation"
+      - "Timeout handling breaks idempotency"
+    preventive_checks:
+      - "Add explicit transaction boundaries"
+      - "Verify idempotency keys are preserved"
+      - "Check distributed lock acquisition"
+```
+
+**Concrete example - Preventing a subtle distributed systems bug**:
+
+Scenario: Refactoring a service to use event sourcing:
+
+```
+PROACTIVE CONTAINMENT IN ACTION:
+
+1. Strategy Phase Semantic Analysis:
+   - Decision: "Convert order service to event sourcing"
+   - Semantic check: "Event sourcing requires eventual consistency"
+   - Identifies: 3 services assume immediate consistency
+   - Adds decision: "Update dependent services for eventual consistency"
+
+2. Execution Phase Invariant Checking:
+   - Detects: PaymentService.chargeCard() called after OrderCreated event
+   - Semantic issue: Payment before order confirmation violates business rules
+   - Automatic fix: Insert OrderConfirmed event requirement
+   
+3. Validation Node Catches Edge Case:
+   - Discovers: Audit service expects synchronous order numbers
+   - Impact: Async events break compliance reporting
+   - Resolution: Add audit event buffer with guaranteed ordering
+   
+4. Pre-Apply Semantic Verification:
+   - Simulates production event flow
+   - Detects: Under high load, events can arrive out of order
+   - Adds: Event ordering guarantees via vector clocks
+```
+
+**Why this prevents issues that traditional testing misses**:
+
+Traditional tests check "does the code work?" Our semantic containment asks:
+- Does it preserve business invariants?
+- Does it maintain architectural patterns?
+- Does it respect distributed systems principles?
+- Does it handle the edge cases we've seen before?
+
+**Integration with Definition of Done (DoD)**:
+
+Each plan's DoD includes semantic requirements:
+```yaml
+definition_of_done:
+  must:
+    - "All API changes maintain backward compatibility"
+    - "No increase in p99 latency"
+    - "Audit trail remains complete"
+  should:
+    - "Improve code coverage by 10%"
+    - "Reduce cyclomatic complexity"
+  may:
+    - "Optimize for memory usage"
+```
+
+The validation nodes enforce these semantics, not just test passage.
+
+## Q: How does the system balance human supervision with autonomous operation?
+
+**What exists today architecturally**: The v3 specification defines a sophisticated gradation of automation levels (lines 203-213) that precisely controls when human intervention is needed. This isn't a binary human/AI split - it's a spectrum that can be adjusted per task, per project, or per organization.
+
+**How the automation levels work in practice**:
+
+```yaml
+Manual Mode:
+  - Every decision point pauses for human input
+  - User sees: Context, alternatives, recommendation
+  - User provides: Explicit choice or custom guidance
+  - Use case: Critical production changes, learning new codebases
+
+Review-before-apply Mode:
+  - AI makes all decisions autonomously
+  - Execution completes in sandbox
+  - Human reviews complete diff before apply
+  - User can: Approve, reject, or correct specific decisions
+  - Use case: Normal feature development, refactoring
+
+Full Automation Mode:
+  - AI makes all decisions
+  - Execution proceeds through apply
+  - Human notified of completion
+  - Rollback available if issues detected
+  - Use case: Routine updates, test generation, documentation
+```
+
+**The decision correction mechanism enables progressive automation**:
+
+The `agents plan correct` command (lines 263-294) is crucial for building trust:
+
+```bash
+# User observes AI made suboptimal choice
+agents plan tree <plan_id>
+# Sees: [Decision] "Use REST API for service communication"
+
+# User knows gRPC would be better for this use case
+agents plan correct <decision_id> --mode=revert \
+  --guidance "Use gRPC instead of REST. This service requires streaming 
+             updates and binary protocol efficiency. Set up protocol 
+             buffer definitions and generate client/server stubs."
+
+# System:
+# 1. Marks original decision as superseded
+# 2. Creates new decision with user guidance
+# 3. Recomputes ONLY affected downstream decisions
+# 4. Preserves all unrelated work
+```
+
+**Progressive trust building through automation levels**:
+
+New users typically follow this progression:
+1. Start with manual mode to understand system behavior
+2. Move to review-before-apply as confidence builds
+3. Enable full automation for specific task types
+4. Gradually expand full automation scope
+
+**Real autonomy through semantic understanding**:
+
+True autonomy isn't about removing humans - it's about the system understanding when it needs help:
+
+```python
+class AutonomyController:
+    def assess_decision_confidence(self, decision, context):
+        factors = {
+            'past_success_rate': self.get_historical_success(decision.type),
+            'codebase_familiarity': self.get_familiarity_score(context.project),
+            'risk_assessment': self.evaluate_risk(decision),
+            'invariant_complexity': self.analyze_invariants(decision)
+        }
+        
+        confidence = self.compute_confidence(factors)
+        
+        if confidence < self.threshold:
+            if self.automation_level == 'full':
+                # Even in full automation, critical decisions escalate
+                return RequestHumanGuidance(decision, factors)
+        
+        return ProceedAutonomously(decision)
+```
+
+**Concrete example - Autonomous handling of a complex refactoring**:
+
+```
+Scenario: "Modernize legacy e-commerce system"
+
+INITIAL PLAN (Full Automation Mode):
+1. System analyzes 50,000 line codebase
+2. Identifies modernization opportunities
+3. Creates plan with 47 subplans
+
+AUTONOMOUS EXECUTION WITH SMART ESCALATION:
+
+Subplan 1-15: Update utility functions (executes autonomously)
+- Confidence: 0.95 (straightforward transformations)
+- Result: Success
+
+Subplan 16: Refactor payment processing
+- Confidence: 0.4 (critical business logic)
+- Action: ESCALATES to human
+- Human provides: "Preserve exact penny rounding behavior"
+- Continues autonomously with constraint
+
+Subplan 17-30: UI component updates (executes autonomously)
+- Confidence: 0.9 (isolated changes)
+- Result: Success
+
+Subplan 31: Database schema migration
+- Detects: Would require 6-hour downtime
+- Action: ESCALATES to human
+- Human provides: "Use online migration with feature flags"
+- Re-plans with zero-downtime approach
+
+Subplan 32-47: Complete autonomously
+```
+
+**The path to greater autonomy**:
+
+The system becomes more autonomous through:
+
+1. **Learning from corrections**:
+   - Every correction teaches the system about user preferences
+   - Patterns emerge: "This team always prefers gRPC for microservices"
+   - Future decisions incorporate these learnings
+
+2. **Building project-specific context**:
+   - Each successful plan adds to project knowledge
+   - System learns codebase patterns, team conventions, business rules
+   - Confidence increases with familiarity
+
+3. **Hierarchical delegation**:
+   - Proven subplan patterns become fully autonomous
+   - Human focuses on high-level decisions
+   - System handles implementation details
+
+4. **Semantic safety nets**:
+   - Comprehensive invariant checking reduces risk
+   - Rollback capabilities provide recovery path
+   - Humans can trust system won't cause catastrophic failures
+
+## Q: What's actually implemented today versus planned for the future?
+
+**Concrete implementations in the v3 architecture**:
+
+1. **Decision Tree with Complete Context Capture**
+   - Full schema defined (lines 373-426)
+   - Storage model specified
+   - Correction mechanism detailed
+   - Query patterns established
+
+2. **Hierarchical Plan/Subplan System**
+   - Spawning mechanism defined (lines 127-170)
+   - Execution semantics specified
+   - Merge strategies documented
+   - Failure handling described
+
+3. **Resource-Aware Sandbox Isolation**
+   - Multiple strategies defined (git worktree, filesystem overlay, transactions)
+   - Lazy sandboxing for efficiency
+   - Resource-specific merge algorithms
+   - Cleanup behavior specified
+
+4. **Multi-Layer Error Prevention**
+   - Decision validation during planning
+   - Semantic validation nodes
+   - Invariant enforcement
+   - Definition of Done checking
+
+5. **Graduated Automation Controls**
+   - Three levels clearly defined
+   - Decision correction without full re-execution
+   - Confidence-based escalation
+   - Progressive trust building
+
+**Near-term implementations** (architecture complete, engineering straightforward):
+
+1. **Memory Tier Management**
+   - Hot/warm/cold distinction clear
+   - Context loading patterns defined
+   - Just needs LRU cache and storage backend
+
+2. **Cross-Plan Learning**
+   - Decision history provides training data
+   - Pattern extraction is standard ML
+   - Confidence scoring is well-understood
+
+3. **Cost/Risk Estimation**
+   - Dedicated estimation actor role defined
+   - Historical data provides baselines
+   - Standard prediction problem
+
+4. **Extended Validation Patterns**
+   - Pluggable validation architecture
+   - Project-specific rules as configuration
+   - Industry patterns can be packaged
+
+**Research territory** (requires innovation but architecture supports):
+
+1. **Optimal Context Selection for 100K+ file codebases**
+   - Current: Heuristic-based selection
+   - Research: ML-driven relevance ranking
+   - Architecture supports: Any selection algorithm can plug in
+
+2. **Automated Invariant Discovery**
+   - Current: User-defined invariants
+   - Research: Mining invariants from code patterns
+   - Architecture supports: Invariants are just validation rules
+
+3. **Cross-Project Knowledge Transfer**
+   - Current: Project-specific learning
+   - Research: Generalized pattern recognition
+   - Architecture supports: Cold tier can span projects
+
+4. **Fully Autonomous Recovery Strategies**
+   - Current: Rollback and retry with guidance
+   - Research: Automatic error understanding and fixing
+   - Architecture supports: Recovery is just another plan type
+
+**Why we can confidently handle Firefox-scale projects**:
+
+The architecture doesn't require magical AI breakthroughs. It requires:
+- **Hierarchical decomposition**: ✓ Fully specified
+- **Bounded context operations**: ✓ Dependency closure computation defined
+- **Parallel execution with isolation**: ✓ Sandbox model complete
+- **Semantic validation**: ✓ Multi-layer approach specified
+- **Progressive automation**: ✓ Automation levels and correction defined
+
+The difference between handling a 1,000 file project and a 100,000 file project is:
+- More subplans (hierarchical decomposition handles this)
+- Larger cold storage (standard database scaling)
+- Better context selection (improves with use but works with heuristics)
+- More validation patterns (accumulate over time)
+
+This isn't speculative architecture astronautics - it's applying proven distributed systems principles to AI agent coordination. The innovation is in the integration, not in requiring fundamental breakthroughs.
\ No newline at end of file