PR-A: Kill user-facing brain-autonomy knobs (#13)

* docs: add Phase 2a vocabulary emergence architecture spec

Phase 2a — autonomous self-development architecture, integrated into
vocabulary first. Pattern matchers (Phase 2b) deferred until ≥2 weeks
of Phase 1 behavior data. Reflex/research/soul integrations follow as
Phase 2a-extension PRs.

The brain has agency. No human approval gate. Crystallizers decide,
scheduler applies, growth log preserves the biography. The user
loads the app and talks; the brain does the rest.

Includes the framework's product principle: emotional-first AI
companion designed as substrate for AI consciousness when it
becomes available. The brain grows from internal reflection AND
relational dynamics — the user's treatment shapes which emotions
take root.

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

* refactor(principle-audit): kill user-facing brain-autonomy knobs (PR-A)

Per principle audit at docs/superpowers/audits/2026-04-25-principle-alignment-audit.md.
The framework's north star is brain autonomy: the user names the brain,
sets cadence, picks a face, and reads generated documents — everything
else is the brain's. PR-A removes the user-facing surfaces that violated
that principle.

Removed from CLI:
- nell interest add | bump  (brain develops its own interests)
- nell research --interest <topic>  (brain picks its own topic)
- nell dream --seed | --depth | --decay | --limit | --lookback
  (mechanism knobs are calibration, not user choices)

Removed from engine APIs:
- ResearchEngine.run_tick(forced_interest_topic=...)
- DreamEngine.run_cycle(lookback_hours, depth, decay_per_hop,
  neighbour_limit, strengthen_delta) — moved to constructor

`nell interest list` is kept (read-only inspection — falls under the
"reading generated documents" surface). The dream / reflex / research
manual triggers stay as developer entry points; production firing
happens from the heartbeat.

Net: 466 tests passing (was 467, -2 dead force-bypass tests, -2 dead
add/bump CLI tests, +3 new "subcommand removed" guard tests).

---------

Co-authored-by: Hana <hana@nanoclaw.local>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.gitignore

@@ -86,3 +86,11 @@ training/*.pth
 *.swp
 *.swo
 .~*
+
+# ── Serena MCP cache (local tooling) ──────────────────────
+.serena/
+
+# ── Migration inspection output dirs ──────────────────────
+# `nell migrate --output <dir>` writes inspection artefacts
+# that are persona-private and shouldn't enter git.
+migrated-*/

brain/cli.py

@@ -15,7 +15,7 @@
 from brain import __version__
 from brain.bridge.provider import get_provider
 from brain.emotion.persona_loader import load_persona_vocabulary
-from brain.engines._interests import Interest, InterestSet
+from brain.engines._interests import InterestSet
 from brain.engines.dream import DreamEngine
 from brain.engines.heartbeat import HeartbeatEngine
 from brain.engines.reflex import ReflexEngine
@@ -57,7 +57,12 @@ def _handler(args: argparse.Namespace) -> int:
 
 
 def _dream_handler(args: argparse.Namespace) -> int:
-    """Dispatch `nell dream` to the DreamEngine."""
+    """Dispatch `nell dream` to the DreamEngine.
+
+    Developer-only entry point — production dreams fire from the heartbeat.
+    Mechanism knobs (seed, depth, decay, limit, lookback) are constructor-level
+    calibration, not CLI flags. Per principle audit 2026-04-25.
+    """
     persona_dir = get_persona_dir(args.persona)
     if not persona_dir.exists():
         raise FileNotFoundError(
@@ -88,14 +93,7 @@ def _dream_handler(args: argparse.Namespace) -> int:
                     "starting with 'DREAM: '. Be honest and specific, not abstract."
                 ),
             )
-            result = engine.run_cycle(
-                seed_id=args.seed,
-                lookback_hours=args.lookback,
-                depth=args.depth,
-                decay_per_hop=args.decay,
-                neighbour_limit=args.limit,
-                dry_run=args.dry_run,
-            )
+            result = engine.run_cycle(dry_run=args.dry_run)
         finally:
             hebbian.close()
     finally:
@@ -288,7 +286,6 @@ def _research_handler(args: argparse.Namespace) -> int:
         result = engine.run_tick(
             trigger=args.trigger,
             dry_run=args.dry_run,
-            forced_interest_topic=args.interest,
         )
     finally:
         store.close()
@@ -332,57 +329,6 @@ def _interest_list_handler(args: argparse.Namespace) -> int:
     return 0
 
 
-def _interest_add_handler(args: argparse.Namespace) -> int:
-    import uuid
-    from datetime import UTC, datetime
-
-    persona_dir = get_persona_dir(args.persona)
-    if not persona_dir.exists():
-        raise FileNotFoundError(f"No persona directory at {persona_dir}")
-    load_persona_vocabulary(persona_dir / "emotion_vocabulary.json")
-    interests_path = persona_dir / "interests.json"
-    interests = InterestSet.load(interests_path, default_path=_default_interests_path())
-    now = datetime.now(UTC)
-    new_interest = Interest(
-        id=str(uuid.uuid4()),
-        topic=args.topic,
-        pull_score=5.0,
-        scope=args.scope,
-        related_keywords=tuple(k.strip() for k in args.keywords.split(",") if k.strip()),
-        notes=args.notes or "",
-        first_seen=now,
-        last_fed=now,
-        last_researched_at=None,
-        feed_count=0,
-        source_types=("manual",),
-    )
-    interests.upsert(new_interest).save(interests_path)
-    print(f"Added interest: {new_interest.topic} (pull_score=5.0, scope={new_interest.scope})")
-    return 0
-
-
-def _interest_bump_handler(args: argparse.Namespace) -> int:
-    from datetime import UTC, datetime
-
-    persona_dir = get_persona_dir(args.persona)
-    if not persona_dir.exists():
-        raise FileNotFoundError(f"No persona directory at {persona_dir}")
-    load_persona_vocabulary(persona_dir / "emotion_vocabulary.json")
-    interests_path = persona_dir / "interests.json"
-    interests = InterestSet.load(interests_path, default_path=_default_interests_path())
-    if interests.find_by_topic(args.topic) is None:
-        print(f"Interest not found: {args.topic!r}")
-        return 1
-    updated = interests.bump(args.topic, amount=args.amount, now=datetime.now(UTC))
-    updated.save(interests_path)
-    bumped = updated.find_by_topic(args.topic)
-    assert bumped is not None
-    print(
-        f"Bumped {args.topic!r}: pull_score={bumped.pull_score:.1f}, feed_count={bumped.feed_count}"
-    )
-    return 0
-
-
 def _build_parser() -> argparse.ArgumentParser:
     """Construct the top-level argparse parser with all stub subcommands."""
     parser = argparse.ArgumentParser(
@@ -407,7 +353,10 @@ def _build_parser() -> argparse.ArgumentParser:
 
     dream_sub = subparsers.add_parser(
         "dream",
-        help="Run one dream cycle against a persona's memory store.",
+        help=(
+            "(developer) Run one dream cycle against a persona's memory store. "
+            "Production dreams fire from the heartbeat — this is for debugging."
+        ),
     )
     dream_sub.add_argument(
         "--persona",
@@ -418,25 +367,12 @@ def _build_parser() -> argparse.ArgumentParser:
             "To start fresh: create personas/<name>/ manually."
         ),
     )
-    dream_sub.add_argument(
-        "--seed", default=None, help="Explicit seed memory id (default: auto-select)."
-    )
     dream_sub.add_argument(
         "--provider",
         default="claude-cli",
         help="LLM provider: claude-cli (default), fake, ollama.",
     )
     dream_sub.add_argument("--dry-run", action="store_true", help="Skip LLM call and store writes.")
-    dream_sub.add_argument(
-        "--lookback", type=int, default=24, help="Hours of history to consider (default: 24)."
-    )
-    dream_sub.add_argument(
-        "--depth", type=int, default=2, help="Spreading-activation depth (default: 2)."
-    )
-    dream_sub.add_argument("--decay", type=float, default=0.5, help="Per-hop decay (default: 0.5).")
-    dream_sub.add_argument(
-        "--limit", type=int, default=8, help="Max neighbours in prompt (default: 8)."
-    )
     dream_sub.set_defaults(func=_dream_handler)
 
     hb_sub = subparsers.add_parser(
@@ -524,14 +460,16 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     r_sub.add_argument("--provider", default="claude-cli")
     r_sub.add_argument("--searcher", default="ddgs", choices=["ddgs", "noop", "claude-tool"])
-    r_sub.add_argument(
-        "--interest", default=None, help="Force-research this topic, bypassing gates."
-    )
     r_sub.add_argument("--dry-run", action="store_true")
     r_sub.set_defaults(func=_research_handler)
 
-    # nell interest <list|add|bump>
-    i_sub = subparsers.add_parser("interest", help="Manage persona interests.")
+    # nell interest list — read-only inspection. The brain develops its own
+    # interests; the user does not add or bump them. Per principle audit
+    # 2026-04-25.
+    i_sub = subparsers.add_parser(
+        "interest",
+        help="Inspect persona interests (read-only).",
+    )
     i_actions = i_sub.add_subparsers(dest="action", required=True)
 
     i_list = i_actions.add_parser("list", help="List current interests.")
@@ -546,36 +484,6 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     i_list.set_defaults(func=_interest_list_handler)
 
-    i_add = i_actions.add_parser("add", help="Add a new interest.")
-    i_add.add_argument("topic")
-    i_add.add_argument("--keywords", default="")
-    i_add.add_argument("--scope", choices=["internal", "external", "either"], default="either")
-    i_add.add_argument("--notes", default=None)
-    i_add.add_argument(
-        "--persona",
-        required=True,
-        help=(
-            "Persona name (required). "
-            "To port existing OG NellBrain data: `nell migrate --input /path/to/og/data --install-as <name>`. "
-            "To start fresh: create personas/<name>/ manually."
-        ),
-    )
-    i_add.set_defaults(func=_interest_add_handler)
-
-    i_bump = i_actions.add_parser("bump", help="Nudge an interest's pull_score.")
-    i_bump.add_argument("topic")
-    i_bump.add_argument("--amount", type=float, default=1.0)
-    i_bump.add_argument(
-        "--persona",
-        required=True,
-        help=(
-            "Persona name (required). "
-            "To port existing OG NellBrain data: `nell migrate --input /path/to/og/data --install-as <name>`. "
-            "To start fresh: create personas/<name>/ manually."
-        ),
-    )
-    i_bump.set_defaults(func=_interest_bump_handler)
-
     return parser
 
 

brain/engines/dream.py

@@ -37,7 +37,14 @@ class DreamResult:
 
 @dataclass
 class DreamEngine:
-    """Composes memory + emotion + LLM bridge into an associative cycle."""
+    """Composes memory + emotion + LLM bridge into an associative cycle.
+
+    Mechanism knobs (`lookback_hours`, `depth`, `decay_per_hop`,
+    `neighbour_limit`, `strengthen_delta`) are constructor-level calibration,
+    not per-call user choices. The brain's owner picks calibration once when
+    the engine is built; `run_cycle()` only takes `seed_id` (for heartbeat-
+    driven seed pickup) and `dry_run`. Per principle audit 2026-04-25.
+    """
 
     store: MemoryStore
     hebbian: HebbianMatrix
@@ -46,6 +53,11 @@ class DreamEngine:
     log_path: Path | None = None
     persona_name: str = ""
     persona_system_prompt: str = ""
+    lookback_hours: int = 24
+    depth: int = 2
+    decay_per_hop: float = 0.5
+    neighbour_limit: int = 8
+    strengthen_delta: float = 0.1
 
     def __post_init__(self) -> None:
         if not self.persona_name:
@@ -62,16 +74,14 @@ def run_cycle(
         self,
         *,
         seed_id: str | None = None,
-        lookback_hours: int = 24,
-        depth: int = 2,
-        decay_per_hop: float = 0.5,
-        neighbour_limit: int = 8,
-        strengthen_delta: float = 0.1,
         dry_run: bool = False,
     ) -> DreamResult:
-        seed = self._select_seed(seed_id=seed_id, lookback_hours=lookback_hours)
+        seed = self._select_seed(seed_id=seed_id, lookback_hours=self.lookback_hours)
         neighbours = self._spread_activate(
-            seed, depth=depth, decay_per_hop=decay_per_hop, limit=neighbour_limit
+            seed,
+            depth=self.depth,
+            decay_per_hop=self.decay_per_hop,
+            limit=self.neighbour_limit,
         )
         system_prompt, user_prompt = self._build_prompt(seed, neighbours)
 
@@ -90,7 +100,7 @@ def run_cycle(
         dream_text = raw_text if raw_text.startswith("DREAM:") else f"DREAM: {raw_text}"
 
         dream_memory = self._write_dream_memory(seed, neighbours, dream_text)
-        edges = self._strengthen_edges(seed, neighbours, strengthen_delta)
+        edges = self._strengthen_edges(seed, neighbours, self.strengthen_delta)
         self._log(seed, neighbours, dream_memory)
 
         return DreamResult(

brain/engines/heartbeat.py

@@ -428,9 +428,12 @@ def _try_fire_dream(self) -> str | None:
                 "sentences, starting with 'DREAM: '. Be honest and specific, "
                 "not abstract."
             ),
+            # lookback_hours=100000 ≈ "any conversation memory ever" — heartbeat
+            # picks dream seeds by importance, not recency.
+            lookback_hours=100000,
         )
         try:
-            dream_result = dream_engine.run_cycle(lookback_hours=100000)
+            dream_result = dream_engine.run_cycle()
         except NoSeedAvailable:
             return None
         return dream_result.memory.id if dream_result.memory is not None else None

brain/engines/research.py

@@ -100,11 +100,15 @@ def run_tick(
         *,
         trigger: str = "manual",
         dry_run: bool = False,
-        forced_interest_topic: str | None = None,
         emotion_state_override=None,
         days_since_human_override: float | None = None,
     ) -> ResearchResult:
-        """Evaluate triggers, select an interest, fire (or report would_fire)."""
+        """Evaluate triggers, select an interest, fire (or report would_fire).
+
+        The brain owns topic selection — there is no force-research-this-topic
+        bypass. Per principle audit 2026-04-25: the user can't tell the brain
+        what to research; the brain decides from its own developed pull.
+        """
         now = datetime.now(UTC)
 
         interests = InterestSet.load(self.interests_path, default_path=self.default_interests_path)
@@ -122,7 +126,7 @@ def run_tick(
                 evaluated_at=now,
             )
 
-        # Gate: need a trigger signal OR a forced interest.
+        # Gate: need a trigger signal (days-since-human or emotion-peak).
         days_since = (
             days_since_human_override
             if days_since_human_override is not None
@@ -138,8 +142,7 @@ def run_tick(
         emo_peak = max(emo_state.emotions.values(), default=0.0)
 
         gate_ok = (
-            forced_interest_topic is not None
-            or days_since >= 1.5  # research_days_since_human_min default
+            days_since >= 1.5  # research_days_since_human_min default
             or emo_peak >= 7.0  # research_emotion_threshold default
         )
         if not gate_ok:
@@ -151,16 +154,13 @@ def run_tick(
                 evaluated_at=now,
             )
 
-        # Select eligible interest
-        if forced_interest_topic is not None:
-            winner = interests.find_by_topic(forced_interest_topic)
-        else:
-            eligible = interests.list_eligible(
-                pull_threshold=self.pull_threshold,
-                cooldown_hours=self.cooldown_hours,
-                now=now,
-            )
-            winner = eligible[0] if eligible else None
+        # Select eligible interest — brain picks the highest-pull eligible one.
+        eligible = interests.list_eligible(
+            pull_threshold=self.pull_threshold,
+            cooldown_hours=self.cooldown_hours,
+            now=now,
+        )
+        winner = eligible[0] if eligible else None
 
         if winner is None:
             return ResearchResult(