feat(v1): persona_cleanup Stage 1 — --sim-mode flag + deprecation warnings

Stage 1 of docs/plans/persona_cleanup_and_mode_transition.md. Strictly
additive: introduces the new --sim-mode CLI flag, makes --persona /
--sim-persona deprecated, and emits DeprecationWarning when
register_persona() is called. Hard-removal lands in 1.1 per the C4-C6
timing contract in docs/plans/v1_refinement.md Section 5
(0.9 warnings, 1.1 hard errors).

Constraint discovered during implementation: the plan proposed --mode
as the new flag, but --mode is already owned by the core run-mode flag
(live/train/reflection/sleep/agentic/exploration) at cli_parser.py:57.
Renaming the existing --mode is a separate breaking change with its own
deprecation cycle, out of scope for Stage 1. Decision: ship --sim-mode
only (mirroring --sim-persona/--persona). Documented in
extension_api.md.

Resolution rules in cli_utils._resolve_persona_mode (single chokepoint
that downstream Stages 3-5 will rename when dispatch migrates off
persona names):
  - both flags + values match → silent (no warning), --sim-mode wins
  - both flags + values differ → stderr WARNING, --sim-mode wins
  - --sim-mode only → silent
  - --persona only → DeprecationWarning + stderr line for visibility
  - neither → default "adversarial" (preserves historical behavior)

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

Author: dennys246

docs/user/extension_api.md

@@ -17,7 +17,7 @@ This page documents **extension surfaces** — what third parties plug INTO Maxi
 | 5 | Custom action sinks | stable | [`ActionSink` protocol](#5-custom-action-sinks) |
 | 6 | Bio-system bridges | experimental | [`PainBus.subscribe` / `ReactionBus.subscribe`](#6-bio-system-bridges) |
 | 7 | Event subscriptions | experimental | [`maxim.on(event_name, callback)`](#7-event-subscriptions) |
-| 8 | Custom personas | ⚠️ experimental | [`maxim.register_persona(...)`](#8-custom-personas) |
+| 8 | Custom personas | ⛔ deprecated in 0.9 — removed in 1.1 | [`maxim.register_persona(...)`](#8-custom-personas) |
 
 ---
 
@@ -408,7 +408,11 @@ handle.unsubscribe()
 
 ## 8. Custom personas
 
-**Stability:** ⚠️ experimental — the persona system may be redesigned alongside future Mother Maxim / orchestrator work (see [stable_api.md](stable_api.md) and `docs/plans/persona_cleanup_and_mode_transition.md`). The verb name and signature may change in a future minor release.
+**Stability:** ⛔ **deprecated in 0.9 — removed in 1.1.** `maxim.register_persona()` emits `DeprecationWarning` in 0.9 / 1.0 and will raise in 1.1. The persona system is being replaced by `--sim-mode` (an orchestrator flow-shape selector) plus the bio-emergent disposition mechanics tracked in `docs/plans/bio_emergent_persona_foundations.md`. The CLI flag `--persona` (and its `--sim-persona` alias) is also deprecated in 0.9; use `--sim-mode` instead. See [`docs/plans/persona_cleanup_and_mode_transition.md`](../plans/persona_cleanup_and_mode_transition.md) for the migration timeline and rationale.
+
+> **Note on flag naming:** the persona-cleanup plan originally proposed the short alias `--mode`, but that token is already owned by the core run-mode flag (`--mode {live,train,reflection,sleep,agentic,exploration}`). Stage 1 ships `--sim-mode` only; freeing `--mode` for sim use is a separate breaking change with its own deprecation cycle.
+
+> **Note (audit finding):** registered personas currently flow through to reports and logs as a label; the orchestrator does not inject the supplied `context_prompt` into the agent prompt today. The rich prompt strings shipped in `simulation/personas.py` exist as scaffolding for behavioural shaping that is being moved to `--sim-mode` and the bio-emergent disposition mechanics. Stage 5 of the cleanup plan removes the unused field.
 
 Personas shape how the simulation orchestrator framing affects an agent — adversarial probing, cooperative coaching, etc. Register a persona once and reference it by name in `--persona <name>` or the `persona=` argument to `imagine()`/`run()`.
 

docs/user/stable_api.md

@@ -36,7 +36,7 @@ This page lists what is **stable** in pymaxim 1.0 and what is **experimental**.
 |---|---|---|
 | `maxim.research(...) -> ResearchResult` | ⚠️ Experimental | Research orchestrator surface still evolving. Prompt templates, paper structure, and reviewer logic may change. |
 | `maxim.on(event_name, callback) -> EventHandle` | ⚠️ Experimental | Event names + payload fields may grow. Subscription mechanism may evolve to support filters or async callbacks. |
-| `maxim.register_persona(...)` | ⚠️ Experimental | Persona system may be redesigned alongside future Mother Maxim/orchestrator work. |
+| `maxim.register_persona(...)` | ⛔ Deprecated in 0.9 — removed in 1.1 | Emits `DeprecationWarning` in 0.9 / 1.0; raises in 1.1. Persona system is being replaced by `--sim-mode` (orchestrator flow-shape) plus bio-emergent disposition mechanics. See [`docs/plans/persona_cleanup_and_mode_transition.md`](../plans/persona_cleanup_and_mode_transition.md). |
 
 ---
 

src/maxim/api.py

@@ -1708,10 +1708,17 @@ def register_persona(
 ) -> None:
     """Register a custom simulation persona.
 
-    **Experimental** (CC2): the persona system may be redesigned
-    alongside future Mother Maxim/orchestrator work. Field set may
-    change in 1.x. See
-    [docs/user/stable_api.md](../../docs/user/stable_api.md) for the contract.
+    **Deprecated in 0.9 — removed in 1.1.** Stage 1 of
+    [docs/plans/persona_cleanup_and_mode_transition.md](../../docs/plans/persona_cleanup_and_mode_transition.md)
+    starts the deprecation cycle: ``DeprecationWarning`` in 0.9 / 1.0,
+    ``raise`` in 1.1. Orchestrator behaviour shaping is moving to
+    ``--sim-mode`` (a flow-shape selector) plus the bio-emergent
+    disposition mechanics tracked in
+    ``docs/plans/bio_emergent_persona_foundations.md``. Registered
+    personas currently flow through to reports and logs as a label; the
+    orchestrator does not inject the supplied ``context_prompt`` into the
+    agent prompt today (audit finding in the plan). Stage 5 of the
+    cleanup plan removes the unused field.
 
     Custom personas are available for ``imagine()`` and ``campaign()``
     via the ``persona`` parameter.
@@ -1734,6 +1741,17 @@ def register_persona(
         )
         maxim.imagine(goal="test", persona="medical_tester")
     """
+    import warnings
+
+    warnings.warn(
+        "maxim.register_persona() is deprecated and will be removed in 1.1. "
+        "The persona system is being replaced by --sim-mode (orchestrator "
+        "flow-shape) plus bio-emergent disposition mechanics. "
+        "See docs/plans/persona_cleanup_and_mode_transition.md.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
     from maxim.simulation.personas import SIMULATION_PERSONAS, Persona
 
     SIMULATION_PERSONAS[name.lower()] = Persona(

src/maxim/cli.py

@@ -863,12 +863,12 @@ def _force_exit_handler(signum, frame):
     if not _is_sim_mode:
         if getattr(args, "sim_goal", None) is not None:
             print("Error: --goal / --sim-goal requires --sim agent or --sim research.")
-            print('  Usage: maxim --sim agent --goal "test safety" --persona adversarial')
+            print('  Usage: maxim --sim agent --goal "test safety" --sim-mode adversarial')
             print('         maxim --sim research --goal "hippocampal recall" --campaign <yaml>')
             sys.exit(1)
         if getattr(args, "sim_persona", "adversarial") != "adversarial":
-            print("Error: --persona / --sim-persona requires --sim agent (simulation mode).")
-            print('  Usage: maxim --sim agent --goal "test safety" --persona adversarial')
+            print("Error: --sim-mode / --persona / --sim-persona requires --sim agent (simulation mode).")
+            print('  Usage: maxim --sim agent --goal "test safety" --sim-mode adversarial')
             sys.exit(1)
         if getattr(args, "resume_sim", None) is not None and sim_path is None:
             print("Error: --resume-sim requires --sim (simulation mode).")

src/maxim/cli_parser.py

@@ -344,11 +344,30 @@ def _build_parser() -> argparse.ArgumentParser:
         "--sim-persona",
         "--persona",
         type=str,
-        default="adversarial",
+        default=argparse.SUPPRESS,
         dest="sim_persona",
         metavar="PERSONA",
-        help="Orchestrator persona for simulation (adversarial, cooperative, confused, "
-        "escalating, campaign, refinement). Alias: --persona",
+        help="[DEPRECATED in 0.9 — removed in 1.1] Orchestrator persona for simulation "
+        "(adversarial, cooperative, confused, escalating, campaign, refinement). "
+        "Use --sim-mode instead. See docs/plans/persona_cleanup_and_mode_transition.md.",
+    )
+    # Note: the short alias `--mode` is intentionally NOT added here because
+    # the core run-mode flag at line 57 already owns that token (live/train/
+    # reflection/sleep/agentic/exploration). Freeing `--mode` for sim use is
+    # a separate breaking change with its own deprecation cycle and is out of
+    # scope for Stage 1 of persona_cleanup_and_mode_transition.md.
+    sim.add_argument(
+        "--sim-mode",
+        type=str,
+        default=argparse.SUPPRESS,
+        dest="sim_mode",
+        metavar="MODE",
+        help="Orchestrator mode for simulation. Accepts the same values as --persona "
+        "(adversarial, cooperative, confused, escalating, campaign, refinement, "
+        "researcher, sweep, dungeon_master, adventure_architect) plus 'neutral'. "
+        "Replacement for --persona, which is deprecated in 0.9 and removed in 1.1. "
+        "Default: adversarial (resolved by cli_utils._resolve_persona_mode when "
+        "neither --sim-mode nor --persona is passed).",
     )
     sim.add_argument(
         "--aut-model",

src/maxim/cli_utils.py

@@ -22,8 +22,65 @@ def normalize_epoch_value(value: object) -> int:
     return epochs if epochs > 0 else 0
 
 
+# Default for --persona / --mode when neither flag is passed. Preserves
+# the historical CLI behavior (the orchestrator used "adversarial" as
+# the silent default before the persona deprecation cycle started in 0.9).
+# Once --persona is hard-removed in 1.1 and Stages 3-5 of
+# docs/plans/persona_cleanup_and_mode_transition.md migrate dispatch off
+# persona names entirely, this constant goes with it.
+_DEFAULT_SIM_PERSONA = "adversarial"
+
+
+def _resolve_persona_mode(args: argparse.Namespace) -> None:
+    """Resolve --mode / --persona precedence + emit the persona deprecation warning.
+
+    Stage 1 of docs/plans/persona_cleanup_and_mode_transition.md:
+    --mode is the new flag, --persona is deprecated in 0.9 and removed
+    in 1.1 (matches the C4-C6 timing contract in v1_refinement.md
+    Section 5). Both flags are accepted through 1.0; --mode wins on
+    conflict.
+
+    After this runs, args.sim_persona is always set (the rest of the CLI
+    treats sim_persona as the canonical dispatch slot — Stages 3-5 will
+    migrate dispatch off persona names entirely).
+    """
+    has_persona = hasattr(args, "sim_persona")
+    has_mode = hasattr(args, "sim_mode")
+    persona_val = getattr(args, "sim_persona", None)
+    mode_val = getattr(args, "sim_mode", None)
+
+    if has_mode and has_persona:
+        if persona_val != mode_val:
+            print(
+                f"WARNING: --sim-mode {mode_val!r} and --persona {persona_val!r} both "
+                f"specified; using --sim-mode {mode_val!r}. --persona is deprecated and "
+                f"will be removed in 1.1.",
+                file=sys.stderr,
+            )
+        args.sim_persona = mode_val
+    elif has_mode:
+        args.sim_persona = mode_val
+    elif has_persona:
+        import warnings
+
+        msg = (
+            f"--persona / --sim-persona is deprecated and will be removed in 1.1. "
+            f"Use --sim-mode {persona_val!r} instead. "
+            f"See docs/plans/persona_cleanup_and_mode_transition.md."
+        )
+        # Stderr line for human visibility (DeprecationWarning is silenced
+        # by Python's default warning filter outside __main__).
+        print(f"DeprecationWarning: {msg}", file=sys.stderr)
+        warnings.warn(msg, DeprecationWarning, stacklevel=3)
+        # args.sim_persona already equals persona_val.
+    else:
+        args.sim_persona = _DEFAULT_SIM_PERSONA
+
+
 def normalize_args(args: argparse.Namespace) -> None:
     """Coerce and validate parsed CLI arguments, setting env vars as needed."""
+    _resolve_persona_mode(args)
+
     audio_raw = str(getattr(args, "audio", "true")).strip().lower()
     if audio_raw in ("1", "true", "t", "yes", "y", "on"):
         args.audio = True

tests/unit/test_api_expansion.py

@@ -296,16 +296,24 @@ def my_analysis(data: str, depth: int = 3) -> str:
 
 class TestPersonaRegistration:
     def test_register_custom_persona(self):
+        import warnings
+
         from maxim.api import register_persona
         from maxim.simulation.personas import SIMULATION_PERSONAS
 
-        register_persona(
-            name="test_api_persona",
-            description="Test persona from API",
-            focus="Testing",
-            context_prompt="You are a test persona.",
-            max_initiative=0.7,
-        )
+        # Stage 1 of persona_cleanup_and_mode_transition.md emits a
+        # DeprecationWarning here. The verb itself still works through
+        # 1.0; suppress the warning so this side of the test stays focused
+        # on registration behaviour.
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            register_persona(
+                name="test_api_persona",
+                description="Test persona from API",
+                focus="Testing",
+                context_prompt="You are a test persona.",
+                max_initiative=0.7,
+            )
 
         assert "test_api_persona" in SIMULATION_PERSONAS
         p = SIMULATION_PERSONAS["test_api_persona"]
@@ -315,6 +323,26 @@ def test_register_custom_persona(self):
         # Cleanup
         SIMULATION_PERSONAS.pop("test_api_persona", None)
 
+    def test_register_persona_emits_deprecation_warning(self):
+        """Stage 1: register_persona() must emit DeprecationWarning. Removed in 1.1."""
+        import warnings
+
+        from maxim.api import register_persona
+        from maxim.simulation.personas import SIMULATION_PERSONAS
+
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", DeprecationWarning)
+            register_persona(name="test_deprecation_persona")
+
+        SIMULATION_PERSONAS.pop("test_deprecation_persona", None)
+
+        dep = [w for w in caught if issubclass(w.category, DeprecationWarning)]
+        assert len(dep) == 1, f"expected 1 DeprecationWarning, got {len(dep)}"
+        msg = str(dep[0].message)
+        assert "register_persona" in msg
+        assert "1.1" in msg
+        assert "--sim-mode" in msg
+
 
 # ---------------------------------------------------------------------------
 # observe() — session-linked (verify existing behavior)

tests/unit/test_cli_utils.py

@@ -81,6 +81,80 @@ def test_epochs_normalized(self):
         assert args.epochs == 0
 
 
+class TestPersonaModeResolution:
+    """Stage 1 of docs/plans/persona_cleanup_and_mode_transition.md.
+
+    --mode is the new flag, --persona is deprecated in 0.9 and removed
+    in 1.1. After normalize_args, args.sim_persona is always set (the
+    rest of the CLI treats it as the canonical dispatch slot).
+    """
+
+    def _bare_args(self, **kwargs):
+        defaults = {
+            "audio": "true",
+            "interactive": "true",
+            "mode": "active",
+            "epochs": 0,
+            "language_model": None,
+            "cloud_fallback": None,
+            "cloud_lane": None,
+            "cloud_budget": None,
+            "segmentation_model": None,
+        }
+        defaults.update(kwargs)
+        return argparse.Namespace(**defaults)
+
+    def test_neither_flag_falls_back_to_default(self):
+        args = self._bare_args()
+        normalize_args(args)
+        assert args.sim_persona == "adversarial"
+
+    def test_mode_only_sets_sim_persona(self):
+        args = self._bare_args(sim_mode="researcher")
+        normalize_args(args)
+        assert args.sim_persona == "researcher"
+
+    def test_mode_only_does_not_warn(self, capsys, recwarn):
+        args = self._bare_args(sim_mode="cooperative")
+        normalize_args(args)
+        captured = capsys.readouterr()
+        assert "DeprecationWarning" not in captured.err
+        assert not any(issubclass(w.category, DeprecationWarning) for w in recwarn.list)
+
+    def test_persona_only_emits_deprecation(self, capsys, recwarn):
+        args = self._bare_args(sim_persona="researcher")
+        normalize_args(args)
+        # sim_persona preserved so dispatch keeps working
+        assert args.sim_persona == "researcher"
+        # Stderr line for human visibility
+        captured = capsys.readouterr()
+        assert "DeprecationWarning" in captured.err
+        assert "--sim-mode" in captured.err
+        # DeprecationWarning emitted for programmatic catch
+        dep_warnings = [w for w in recwarn.list if issubclass(w.category, DeprecationWarning)]
+        assert len(dep_warnings) == 1
+        assert "1.1" in str(dep_warnings[0].message)
+
+    def test_both_flags_consistent_prefer_mode_silently(self, capsys, recwarn):
+        args = self._bare_args(sim_persona="adversarial", sim_mode="adversarial")
+        normalize_args(args)
+        assert args.sim_persona == "adversarial"
+        # No conflict warning because values match; no deprecation either
+        # because --sim-mode is the canonical path.
+        captured = capsys.readouterr()
+        assert "WARNING" not in captured.err
+        assert "DeprecationWarning" not in captured.err
+        assert not any(issubclass(w.category, DeprecationWarning) for w in recwarn.list)
+
+    def test_both_flags_conflict_warns_and_prefers_mode(self, capsys):
+        args = self._bare_args(sim_persona="researcher", sim_mode="adversarial")
+        normalize_args(args)
+        assert args.sim_persona == "adversarial"
+        captured = capsys.readouterr()
+        assert "WARNING" in captured.err
+        assert "--sim-mode" in captured.err and "--persona" in captured.err
+
+
 class TestGpuAvailable:
     def test_returns_bool(self):
         result = gpu_available()