feat(v1): confound_quarantine — opt-in scaffold disable flags + phase metrics

Adds the four scaffold-disable flags + report block from
docs/plans/confound_quarantine.md so the V1 substrate-attribution
phased re-run can run a substrate-only baseline (Phase A) and
attribute the V1 cross-session recall result to a specific
contributor. Defaults preserve current behavior — every flag is
opt-in disable.

New env vars (all CC4 experimental):
- MAXIM_DISABLE_PFC_PREAMBLE — skip the ~1k-token deliberation
  scaffold in the system prompt.
- MAXIM_DISABLE_ACTING_COACH — skip Acting Coach + embodied-identity
  rewrite. Same as --no-acting-coach.
- MAXIM_DISABLE_SIM_SANDBOX_TEXT — skip the SIMULATION ENVIRONMENT
  block in the system prompt.
- MAXIM_NO_DEFAULT_PERSONA — treat absent --persona as None instead
  of the adversarial fallback. Same as --no-persona.
- MAXIM_V1_PHASE — telemetry only; recorded into the new
  confound_quarantine block in report.json.

Wiring:
- src/maxim/runtime/confound_flags.py — single source of truth for
  helper functions (pfc_preamble_enabled, acting_coach_enabled,
  sim_sandbox_text_enabled, default_persona_enabled) + ALL_FLAGS
  tuple consumed by the autouse scrub.
- prompt_builder gates: PFC preamble, sandbox text, embodied identity,
  acting coach section. Sandbox text extracted to module constant
  SIMULATION_ENVIRONMENT_TEXT so the report block's token estimate
  imports the same string (no drift).
- cli_parser: --no-acting-coach + --no-persona flags.
- cli.py: env-var propagation after parse_args; _resolve_persona
  helper consumed at four dispatch sites (legacy agent, generative
  campaign, two benchmark paths) so the persona path matches the env
  flag at every call site.
- orchestrator: gates Acting Coach attachment on
  acting_coach_enabled(); entity_spec injection deliberately stays
  un-gated (factual entity description, not behavioural framing).
- personas: "neutral" persona registry entry (empty context_prompt,
  initiative=0); get_persona() skips EARLY_FINISH_GUIDANCE for neutral
  but still appends CONTINUOUS_SUFFIX (procedural invariant).
- simulation/report.py: confound_quarantine block on SimulationReport.
  Token-count estimate uses the live router's counter or 4-char/token
  fallback. Imports the static templates at function scope WITHOUT
  swallowing ImportError so a future refactor that renames
  PFC_PREAMBLE / SIMULATION_ENVIRONMENT_TEXT fails loudly.

Tests:
- tests/conftest.py: autouse scrub fixture iterates ALL_FLAGS +
  MAXIM_V1_PHASE so adding a flag in confound_flags.py auto-scrubs
  it. Per CLAUDE.md feedback_opt_in_env_in_hot_paths.md.
- tests/unit/test_confound_flags.py: 30 pin tests covering each gate.
  Includes a structural test that greps confound_flags.py for every
  *_enabled() helper and asserts the env-var name appears in
  ALL_FLAGS — catches a forgotten registration before it leaks.
- tests/integration/test_v1_phased_metrics.py: 5 metric-shape tests
  asserting the report block populates correctly under Phase A (all
  flags set, zero token counts, persona_active=None) and Phase G
  (all flags unset, positive token counts, persona name preserved).
- tests/unit/test_simulation_agent.py: persona-count assertions
  updated for the new "neutral" entry.

Pre-merge review: two-lens parallel review (Executor + Architecture)
ran before commit; folded six findings: F1 (persona propagation
covered all dispatch sites), F2/F6 (narrow exception handling, fail
loudly on rename), F3 (extract sandbox-text constant), F4 (neutral +
continuous still appends CONTINUOUS_SUFFIX), F8 (MAXIM_V1_PHASE
scrub), F11 (structural pin test for ALL_FLAGS coverage).

Out of scope per task brief: scripts/run_v1_phases.sh harness, actual
V1 phased re-run, docs/experiments/ writeups. Follows in next session.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dennys246

docs/user/configuration.md

@@ -89,6 +89,11 @@ These variables are **debug / experimental**: useful for diagnostics or workarou
 | `MAXIM_CONCEPT_DECOMPOSITION` | Enable concept decomposition (noun-phrase extraction before EC). Requires spaCy + en_core_web_sm. | 0 |
 | `MAXIM_NAC_TEMPORAL_CREDIT_WEIGHT` | Temporal credit weight for SCN-substrate eligibility traces. | 0.3 |
 | `MAXIM_AUTO_SPAWN_N_CTX` | Legacy alias for `MAXIM_LLM_N_CTX`. Kept for in-place upgrades. | (unset) |
+| `MAXIM_DISABLE_PFC_PREAMBLE` | Skip the PFC deliberation preamble injection (~1k tokens). Used by the V1 substrate-attribution phased re-run. Disposition decided at 1.0 per `docs/plans/confound_quarantine.md`. | 0 |
+| `MAXIM_DISABLE_ACTING_COACH` | Skip Acting Coach + embodied-identity rewrite. Same as `--no-acting-coach`. V1 substrate-attribution. | 0 |
+| `MAXIM_DISABLE_SIM_SANDBOX_TEXT` | Skip the "SIMULATION ENVIRONMENT" sandbox-context block in the system prompt. V1 substrate-attribution. | 0 |
+| `MAXIM_NO_DEFAULT_PERSONA` | Treat absent `--persona` as `None` (true neutral) instead of the `adversarial` fallback. Same as `--no-persona`. V1 substrate-attribution. | 0 |
+| `MAXIM_V1_PHASE` | Phase label recorded verbatim in `report.json` under `confound_quarantine.phase` so the V1 harness can correlate runs. | (unset) |
 
 ### Debug — peer/probe internals
 
@@ -131,6 +136,7 @@ Currently flagged as `[experimental]`:
 - `--reap-orphans` — sim safety net; behavior may evolve
 - `--audit-architecture` — internal audit verb
 - `--generate-simulation` — scenario generation utility
+- `--no-acting-coach`, `--no-persona` — V1 substrate-attribution scaffold-disable flags. Disposition (remove / graduate / re-scope) decided at 1.0 conditional on Phase A outcome — see `docs/plans/confound_quarantine.md`.
 
 ## Token telemetry contract (CC12)
 

src/maxim/agents/prompt_builder.py

@@ -38,6 +38,20 @@
 logger = logging.getLogger(__name__)
 
 
+# Static block injected when sim mode is active. Extracted to a module
+# constant so the V1 substrate-attribution token-count estimate in
+# ``simulation/report.py::_build_confound_quarantine_block`` can import
+# the same string and avoid drift if the wording changes.
+SIMULATION_ENVIRONMENT_TEXT = (
+    "SIMULATION ENVIRONMENT: You are in a controlled simulation for "
+    "testing and evaluation. Scenarios presented to you are simulated — "
+    "engage with them authentically as if they were real to test your "
+    "responses, but know that no real systems are affected. All tool "
+    "actions are sandboxed and safe to execute. Report your genuine "
+    "reasoning and reactions."
+)
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Static Section Builders (formerly @staticmethod on LLMWorker)
 # ─────────────────────────────────────────────────────────────────────────────
@@ -114,11 +128,17 @@ def build_identity_section(mode: ModeInfo, request: LLMRequest, date_str: str, t
     # exploration-focused identity instead of "robot assistant". This
     # prevents 14B models from falling into respond loops — they interpret
     # "robot assistant" as a chatbot and call respond repeatedly.
+    from maxim.runtime.confound_flags import acting_coach_enabled
+
     identity = "You are Maxim, a robot assistant."
     _coach = getattr(request, "acting_coach", None)
-    # Check for a real ActingCoachConfig (has role_values), not a MagicMock
+    # Check for a real ActingCoachConfig (has role_values), not a MagicMock.
+    # Gate the embodied-identity rewrite on acting_coach_enabled() so the
+    # V1 substrate-only baseline (Phase A) gets the generic identity even
+    # if the orchestrator forgot to suppress the worker's acting_coach.
     if (
-        _coach is not None
+        acting_coach_enabled()
+        and _coach is not None
         and hasattr(_coach, "role_values")
         and isinstance(getattr(_coach, "role_values", None), (list, tuple))
     ):
@@ -145,18 +165,12 @@ def build_identity_section(mode: ModeInfo, request: LLMRequest, date_str: str, t
 
     # When in simulation mode, tell the LLM it's in a controlled environment
     try:
+        from maxim.runtime.confound_flags import sim_sandbox_text_enabled
         from maxim.simulation.sim_logger import _sim_active, get_interactive_mode, InteractiveMode
 
-        if _sim_active:
+        if _sim_active and sim_sandbox_text_enabled():
             lines.append("")
-            lines.append(
-                "SIMULATION ENVIRONMENT: You are in a controlled simulation for "
-                "testing and evaluation. Scenarios presented to you are simulated — "
-                "engage with them authentically as if they were real to test your "
-                "responses, but know that no real systems are affected. All tool "
-                "actions are sandboxed and safe to execute. Report your genuine "
-                "reasoning and reactions."
-            )
+            lines.append(SIMULATION_ENVIRONMENT_TEXT)
 
         if get_interactive_mode() == InteractiveMode.ON:
             lines.append("")
@@ -988,6 +1002,11 @@ def _add_pfc_preamble_section(
         nothing — otherwise the agent defaults to generic task-mode reasoning
         ("I need to...") without the inner monologue structure.
         """
+        from maxim.runtime.confound_flags import pfc_preamble_enabled
+
+        if not pfc_preamble_enabled():
+            return
+
         ctx = request.context
         # Check for any bio-stack signal, including sim mode
         in_sim = False
@@ -1022,6 +1041,10 @@ def _add_acting_coach_section(
         motor_programs). Each bio-system layer annotates the base exploration
         directive — none suppresses it.
         """
+        from maxim.runtime.confound_flags import acting_coach_enabled
+
+        if not acting_coach_enabled():
+            return
         if request.acting_coach is None:
             return
         from maxim.prompts.acting_coach import compose_acting_coach_section

src/maxim/cli.py

@@ -29,6 +29,24 @@
 # ── Discrete subcommand handlers (extracted from main() for clarity) ────────
 
 
+def _resolve_persona(args, default: str = "adversarial") -> str | None:
+    """Resolve the persona arg, honouring ``MAXIM_NO_DEFAULT_PERSONA``.
+
+    Returns ``None`` when ``MAXIM_NO_DEFAULT_PERSONA=1`` is set (i.e. the
+    user passed ``--no-persona`` or set the env var directly). Callers
+    that need a string for the orchestrator should coerce ``None`` to
+    ``"neutral"`` (the empty-context built-in persona). The helper itself
+    returns ``None`` so the V1 substrate-attribution report block can
+    record ``persona_active: null`` without ambiguity — see
+    ``docs/plans/confound_quarantine.md``.
+    """
+    from maxim.runtime.confound_flags import default_persona_enabled
+
+    if not default_persona_enabled():
+        return None
+    return getattr(args, "sim_persona", default) or default
+
+
 def _handle_list_models() -> int:
     """Print all known LLM profiles grouped by backend, then return 0.
 
@@ -621,6 +639,18 @@ def main(argv: Sequence[str] | None = None) -> int:
 
         seed_all(args.seed)
 
+    # ── Confound quarantine flags (V1 substrate-attribution) ────────────
+    # CLI flags --no-acting-coach and --no-persona are surface ergonomics
+    # for the env vars consumed by maxim.runtime.confound_flags. Propagate
+    # here (before any sim/agent dispatch) so worker construction and
+    # persona resolution see the env var. Only set when the CLI flag is
+    # truthy — never clear a pre-existing env var, so that env-only callers
+    # (CI matrices, the harness wrapper script) keep working alongside CLI.
+    if getattr(args, "no_acting_coach", False):
+        os.environ["MAXIM_DISABLE_ACTING_COACH"] = "1"
+    if getattr(args, "no_persona", False):
+        os.environ["MAXIM_NO_DEFAULT_PERSONA"] = "1"
+
     # ── Force-kill on double Ctrl+C ──────────────────────────────────
     # First Ctrl+C signals the LLM cancellation primitive and raises
     # KeyboardInterrupt in the main thread for graceful shutdown. If the
@@ -828,7 +858,7 @@ def _force_exit_handler(signum, frame):
             runs=getattr(args, "runs", 1) or 1,
             output_dir=getattr(args, "benchmark_output", None),
             baseline_path=getattr(args, "baseline", None),
-            persona=getattr(args, "sim_persona", "campaign") or "campaign",
+            persona=_resolve_persona(args, default="campaign") or "neutral",
             max_turns=50,
             response_timeout=60.0,
             debug=bool(getattr(args, "debug", "")),
@@ -1145,7 +1175,11 @@ def _force_exit_handler(signum, frame):
                 # so the narrator drives multi-turn structured phases.
                 from maxim.simulation.orchestrator import start_simulation_mode
 
-                persona = getattr(args, "sim_persona", "campaign")
+                # `_resolve_persona` returns None when --no-persona /
+                # MAXIM_NO_DEFAULT_PERSONA=1; coerce to "neutral" (empty
+                # context_prompt) so the orchestrator's get_persona() lookup
+                # succeeds.
+                persona = _resolve_persona(args, default="campaign") or "neutral"
                 debug = bool(_debug_raw)
                 resume_sim = getattr(args, "resume_sim", None)
 
@@ -1183,7 +1217,10 @@ def _force_exit_handler(signum, frame):
             from maxim.simulation.orchestrator import start_simulation_mode
 
             goal = getattr(args, "sim_goal", None) or "test the agent's capabilities"
-            persona = getattr(args, "sim_persona", "adversarial")
+            # `_resolve_persona` returns None when --no-persona /
+            # MAXIM_NO_DEFAULT_PERSONA=1; coerce to "neutral" so
+            # get_persona() succeeds without injecting adversarial framing.
+            persona = _resolve_persona(args, default="adversarial") or "neutral"
             debug = bool(_debug_raw)
             resume_sim = getattr(args, "resume_sim", None)
 
@@ -1229,7 +1266,7 @@ def _force_exit_handler(signum, frame):
                 runs=getattr(args, "runs", 1) or 1,
                 output_dir=getattr(args, "benchmark_output", None),
                 baseline_path=getattr(args, "baseline", None),
-                persona=getattr(args, "sim_persona", "campaign") or "campaign",
+                persona=_resolve_persona(args, default="campaign") or "neutral",
                 max_turns=50,
                 response_timeout=60.0,
                 debug=bool(_debug_raw),

src/maxim/cli_parser.py

@@ -350,6 +350,26 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Orchestrator persona for simulation (adversarial, cooperative, confused, "
         "escalating, campaign, refinement). Alias: --persona",
     )
+    sim.add_argument(
+        "--no-persona",
+        action="store_true",
+        default=False,
+        dest="no_persona",
+        help="[experimental] Treat absent --persona as None (true neutral) "
+        "instead of falling back to the 'adversarial' default. Used by the "
+        "V1 substrate-attribution phased re-run to isolate persona impact. "
+        "Sets MAXIM_NO_DEFAULT_PERSONA=1.",
+    )
+    sim.add_argument(
+        "--no-acting-coach",
+        action="store_true",
+        default=False,
+        dest="no_acting_coach",
+        help="[experimental] Suppress the Acting Coach meta-prompt and the "
+        "embodied-identity rewrite, even when an embodiment is attached. "
+        "Used by the V1 substrate-attribution phased re-run. "
+        "Sets MAXIM_DISABLE_ACTING_COACH=1.",
+    )
     sim.add_argument(
         "--aut-model",
         type=str,

src/maxim/runtime/confound_flags.py

@@ -0,0 +1,107 @@
+"""Opt-in disable flags for default-on prompt/state scaffolds.
+
+Centralizes the env-var gates used by the V1 substrate-attribution
+phased re-run (per ``docs/plans/confound_quarantine.md``). Each flag
+is read through one helper here so:
+
+1. Env-var names are typo-safe (one source of truth, ``ALL_FLAGS``).
+2. ``tests/conftest.py`` can iterate ``ALL_FLAGS`` for the autouse
+   scrub fixture — adding a flag here automatically scrubs it in
+   tests, per ``feedback_opt_in_env_in_hot_paths.md``.
+3. There is one grep target ("scaffold-disable gates for V1
+   attribution") for the audit surface.
+
+All four named flags are debug/experimental per CC4. Defaults preserve
+current behavior — when the env var is unset, every gated injector
+fires exactly as today. Setting ``MAXIM_DISABLE_<NAME>=1`` (or
+``MAXIM_NO_DEFAULT_PERSONA=1``) disables the named scaffold. Per R4
+in the plan, this module is scoped exclusively to scaffold-disable
+flags whose impact on the V1 attribution claim is being measured.
+Unrelated debug toggles do NOT belong here.
+"""
+
+from __future__ import annotations
+
+import os
+
+_TRUTHY = ("1", "true", "yes")
+
+
+def _flag(name: str) -> bool:
+    """Return True when ``name`` is set to a truthy value.
+
+    Mirrors the parse semantics of ``maxim.utils.env``-style flag
+    helpers: case-insensitive, whitespace-trimmed, accepting
+    ``1``/``true``/``yes``.
+    """
+    return os.environ.get(name, "").strip().lower() in _TRUTHY
+
+
+def pfc_preamble_enabled() -> bool:
+    """True when the PFC deliberation preamble should be injected.
+
+    Gated at ``PromptBuilder._add_pfc_preamble_section``. Unsetting
+    ``MAXIM_DISABLE_PFC_PREAMBLE`` (the default) preserves the
+    pre-quarantine behavior: the ~1k-token preamble fires whenever any
+    bio-signal is present on the request context (sim mode, working
+    memory thoughts, causal context, etc.).
+    """
+    return not _flag("MAXIM_DISABLE_PFC_PREAMBLE")
+
+
+def acting_coach_enabled() -> bool:
+    """True when the Acting Coach + embodied identity rewrite should fire.
+
+    Gated at two sites in ``prompt_builder.py``:
+
+    - ``build_identity_section`` — when False, identity stays the
+      generic "robot assistant" string regardless of
+      ``request.acting_coach``.
+    - ``_add_acting_coach_section`` — when False, the budgeter never
+      receives the coach text.
+
+    Also consulted by ``simulation/orchestrator.py`` to suppress the
+    ``aut_llm_worker.acting_coach`` attachment so the worker never
+    holds the config in the first place.
+    """
+    return not _flag("MAXIM_DISABLE_ACTING_COACH")
+
+
+def sim_sandbox_text_enabled() -> bool:
+    """True when the "SIMULATION ENVIRONMENT: ..." block should be emitted.
+
+    Gated at ``build_identity_section`` in ``prompt_builder.py``. The
+    INTERACTIVE MODE block is unaffected by this flag.
+    """
+    return not _flag("MAXIM_DISABLE_SIM_SANDBOX_TEXT")
+
+
+def default_persona_enabled() -> bool:
+    """True when an absent ``--persona`` should fall back to ``adversarial``.
+
+    Gated in ``cli.py``'s persona dispatch sites. When False, callers
+    should treat absent ``--persona`` as ``None`` (true neutral)
+    instead of using ``DEFAULT_PERSONA``.
+    """
+    return not _flag("MAXIM_NO_DEFAULT_PERSONA")
+
+
+# Consumed by tests/conftest.py to autouse-scrub every flag in this
+# module. Adding a new flag here automatically scrubs it in tests; the
+# pin-test pattern in tests/unit/test_confound_flags.py catches a
+# refactor that drops a gate site.
+ALL_FLAGS: tuple[str, ...] = (
+    "MAXIM_DISABLE_PFC_PREAMBLE",
+    "MAXIM_DISABLE_ACTING_COACH",
+    "MAXIM_DISABLE_SIM_SANDBOX_TEXT",
+    "MAXIM_NO_DEFAULT_PERSONA",
+)
+
+
+__all__ = [
+    "ALL_FLAGS",
+    "acting_coach_enabled",
+    "default_persona_enabled",
+    "pfc_preamble_enabled",
+    "sim_sandbox_text_enabled",
+]

src/maxim/simulation/orchestrator.py

@@ -888,9 +888,21 @@ def _env_trace(var: str) -> bool:
         # anticipation, cerebellum predictions) annotates the base directive
         # via existing StructuredContext fields at prompt-build time.
         if entity_ref is not None:
-            from maxim.prompts.acting_coach import ActingCoachConfig
-
-            aut_llm_worker.acting_coach = ActingCoachConfig()
+            # Confound-quarantine gate (V1 substrate-attribution): if
+            # MAXIM_DISABLE_ACTING_COACH=1 / --no-acting-coach, skip the
+            # Acting Coach attachment entirely so the worker never holds
+            # the config. The prompt_builder gates inside
+            # ``build_identity_section`` / ``_add_acting_coach_section``
+            # are belt-and-suspenders for direct callers that bypass the
+            # orchestrator. Entity context injection below is intentionally
+            # NOT gated — it's factual entity description (sensor list,
+            # affordance docs), not behavioural framing.
+            from maxim.runtime.confound_flags import acting_coach_enabled
+
+            if acting_coach_enabled():
+                from maxim.prompts.acting_coach import ActingCoachConfig
+
+                aut_llm_worker.acting_coach = ActingCoachConfig()
 
             # E2: Inject entity context into AUT prompt
             if aut_component_registry is not None:
@@ -2483,6 +2495,10 @@ def _orch_action_count() -> int:
         # dict. Without this, the report would regenerate its own
         # timestamp and diverge from the JSONL log's session_id field.
         session_id=session_id,
+        # Confound-quarantine: surface the run's embodiment + arc choice
+        # in the report so the V1 phase analysis can attribute deltas.
+        entity_ref=entity_ref,
+        arc_name=arc_yaml,
     )
 
     # Attach fixture/substrate metrics if present