Merge pull request #12 from hanamorix/post-week-4-tech-debt

Post-Week-4 tech-debt cleanup — compact CLI + SHA verify + 2 docs

Author: hanamorix

brain/cli.py

@@ -170,23 +170,38 @@ def _heartbeat_handler(args: argparse.Namespace) -> int:
             f"  dream: {'would fire' if result.dream_id else (result.dream_gated_reason or 'gated')}"
         )
     else:
+        verbose = getattr(args, "verbose", False)
         print(f"Heartbeat tick complete ({args.trigger}).")
         print(f"  elapsed: {result.elapsed_seconds / 3600:.2f}h")
         print(f"  decayed: {result.memories_decayed} memories, pruned {result.edges_pruned} edges")
+
+        # Dream: show fires + interesting gates. Suppress "not_due" by default.
         if result.dream_id:
             print(f"  dream fired: {result.dream_id}")
-        else:
+        elif verbose or (result.dream_gated_reason and result.dream_gated_reason != "not_due"):
             print(f"  dream gated: {result.dream_gated_reason or 'gated'}")
+
+        # Reflex: show fires. Suppress "evaluated, nothing fired" unless --verbose.
         if result.reflex_fired:
             print(f"  reflex fired: {', '.join(result.reflex_fired)}")
-        elif result.reflex_skipped_count > 0:
+        elif verbose and result.reflex_skipped_count > 0:
             print(f"  reflex evaluated ({result.reflex_skipped_count} arc(s) skipped)")
+
+        # Research: show fires + interesting gates (no_eligible_interest,
+        # no_interests_defined, research_raised). Suppress not_due + reflex_won_tie
+        # by default.
         if result.research_fired:
             print(f"  research fired: {result.research_fired}")
-        elif result.research_gated_reason and result.research_gated_reason != "not_due":
+        elif result.research_gated_reason and (
+            verbose or result.research_gated_reason not in ("not_due", "reflex_won_tie")
+        ):
             print(f"  research gated: {result.research_gated_reason}")
+
+        # Interest bumps: show only if > 0 (already compact). Verbose adds zero.
         if result.interests_bumped > 0:
             print(f"  interests bumped: {result.interests_bumped}")
+        elif verbose:
+            print("  interests bumped: 0")
     return 0
 
 
@@ -454,6 +469,12 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Web searcher for research engine: ddgs (default), noop, claude-tool.",
     )
     hb_sub.add_argument("--dry-run", action="store_true")
+    hb_sub.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show all engine outcomes including gated reasons + zero-count engines. "
+        "Default output is compact — events shown, non-events hidden.",
+    )
     hb_sub.set_defaults(func=_heartbeat_handler)
 
     rf_sub = subparsers.add_parser(

brain/emotion/influence.py

@@ -53,6 +53,18 @@ def to_dict(self) -> dict[str, Any]:
 # Emotion → tone bias mapping. Only triggers when the emotion is dominant
 # and above a minimum intensity. Immutable tuple so callers can't accidentally
 # corrupt rule matching via `influence._TONE_RULES.append(...)`.
+#
+# Soft-coupling note (post vocabulary-split):
+#   `creative_hunger` is no longer in the framework baseline — it lives in
+#   per-persona emotion_vocabulary.json since the 2026-04-25 split. This rule
+#   only fires when the persona's *currently dominant* emotion is named
+#   `creative_hunger`, so personas that don't register that name simply never
+#   hit the rule (graceful no-op). Other personas can opt in to the same
+#   tone bias by registering an emotion with that exact name in their
+#   vocabulary file. Future work (Phase 2 emergence + Tauri GUI) may move
+#   tone bias to a per-emotion field in the persona's vocabulary so this
+#   table doesn't have to know persona-specific names at all — for now,
+#   the soft coupling is documented + intentional.
 _TONE_RULES: tuple[tuple[str, float, str], ...] = (
     ("grief", 6.0, "tender"),
     ("tenderness", 7.0, "tender"),

brain/emotion/vocabulary.py

@@ -19,6 +19,11 @@
 from dataclasses import dataclass
 from typing import Literal
 
+# `nell_specific` retained for backwards-compat — pre-vocabulary-split persona
+# files in the wild may still contain entries with this category. New baseline
+# entries use only "core" or "complex"; new persona-loaded entries use only
+# "persona_extension". The Literal accepts `nell_specific` so loaders don't
+# reject older files outright.
 EmotionCategory = Literal["core", "complex", "nell_specific", "persona_extension"]
 
 

brain/migrator/cli.py

@@ -249,7 +249,16 @@ def _ensure_clobber_safe(path: Path, force: bool, kind: str) -> None:
 
 
 def _verify_sources_unchanged(og_dir: Path, manifest: list[FileManifest]) -> None:
-    """Re-stat each source file; abort if any size differs from manifest."""
+    """Re-stat + re-hash each source file; abort if size or SHA-256 differs.
+
+    Size mismatch catches the obvious case (file truncated/grown). SHA-256
+    catches the harder case where same-byte-length content was mutated
+    during the migration window (e.g., a stale OG bridge writing fresh
+    JSON of identical length). The hash was computed by OGReader during
+    the initial manifest pass; we just compare it.
+    """
+    import hashlib
+
     for m in manifest:
         path = og_dir / m.relative_path
         st = path.stat()
@@ -258,6 +267,13 @@ def _verify_sources_unchanged(og_dir: Path, manifest: list[FileManifest]) -> Non
                 f"Source file {path} changed size during migration "
                 f"(was {m.size_bytes}, now {st.st_size}). Aborting."
             )
+        current_sha = hashlib.sha256(path.read_bytes()).hexdigest()
+        if current_sha != m.sha256:
+            raise RuntimeError(
+                f"Source file {path} changed content during migration "
+                f"(SHA-256 mismatch: was {m.sha256[:12]}..., now "
+                f"{current_sha[:12]}...). Aborting."
+            )
 
 
 def _inspect_cmds(work_dir: Path) -> list[str]:

tests/unit/brain/engines/test_cli_heartbeat.py

@@ -104,3 +104,52 @@ def test_nell_heartbeat_unknown_trigger_rejected(nell_persona: Path) -> None:
 
     with pytest.raises(SystemExit):
         main(["heartbeat", "--persona", "nell", "--trigger", "frobnicate", "--provider", "fake"])
+
+
+def test_nell_heartbeat_compact_output_suppresses_not_due(
+    nell_persona: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """Default output suppresses 'dream gated: not_due' and similar non-events."""
+    from brain.cli import main
+
+    main(["heartbeat", "--persona", "nell", "--trigger", "open", "--provider", "fake"])  # init
+    main(["heartbeat", "--persona", "nell", "--trigger", "close", "--provider", "fake"])
+    out = capsys.readouterr().out
+
+    # The active tick should NOT print "dream gated: not_due" by default
+    assert "dream gated: not_due" not in out
+    # And should NOT print "research gated: reflex_won_tie" or "research gated: not_due"
+    assert "research gated: not_due" not in out
+    assert "research gated: reflex_won_tie" not in out
+    # And should NOT print "interests bumped: 0"
+    assert "interests bumped: 0" not in out
+    # But the basic heartbeat lines should still be there
+    assert "Heartbeat tick complete" in out
+    assert "decayed:" in out
+
+
+def test_nell_heartbeat_verbose_shows_all_gated_reasons(
+    nell_persona: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """--verbose flag re-enables non-event lines (dream gated: not_due, etc)."""
+    from brain.cli import main
+
+    main(["heartbeat", "--persona", "nell", "--trigger", "open", "--provider", "fake"])  # init
+    main(
+        [
+            "heartbeat",
+            "--persona",
+            "nell",
+            "--trigger",
+            "close",
+            "--provider",
+            "fake",
+            "--verbose",
+        ]
+    )
+    out = capsys.readouterr().out
+
+    # Verbose mode shows dream gated even for not_due
+    assert "dream gated:" in out
+    # Verbose mode shows interests bumped: 0
+    assert "interests bumped: 0" in out