v5.0.3 — Opus 4.7 vocabulary alignment + mermaid diagrams

CHANGELOG.md

@@ -5,6 +5,74 @@ All notable changes to Orchestra will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.3] - 2026-05-14
+
+Opus 4.7 vocabulary alignment. Additive, non-breaking.
+
+### Added
+
+- `DEPTH_TO_EFFORT` mapping in `parameter_locker.py` aligning Orchestra's depth
+  tiers with Anthropic's `output_config.effort` levels
+  (`MINIMAL→"low"`, `STANDARD→"medium"`, `DEEP→"high"`, `ULTRADEEP→"xhigh"`).
+  On Opus 4.7, `thinking.budget_tokens` is removed (400 error); `effort` is the
+  correct knob. `xhigh` is new on 4.7 — recommended for coding/agentic work.
+- `DEPTH_TO_EFFORT` exported from the `orchestra` top-level package alongside
+  the existing `DEPTH_BUDGETS`.
+- "Scope of Determinism" section in `THINKINGMACHINES_COMPLIANCE.md`
+  distinguishing Orchestra's batch-invariant routing (deterministic per He2025)
+  from Claude API output (not deterministic, especially under adaptive thinking).
+- New `TestDepthToEffort` class in `tests/test_parameter_locker.py`.
+
+### Changed
+
+- Softened the all-caps imperatives in `claude_code_hook.py` `expert_guidance`
+  prose (`EMPATHY FIRST.`, `BREAK DOWN`, etc.) to conditional phrasing.
+  Opus 4.7 follows literal instructions more strictly than 4.6; the previous
+  aggressive imperative pattern overtriggered. Routing behavior unchanged.
+
+### Compatibility
+
+- `DEPTH_BUDGETS` remains exported and unchanged. Downstream consumers of
+  `cognitive-orchestra` are not affected.
+- `ThinkDepth` enum members and `.value` strings unchanged
+  (`"minimal"`, `"standard"`, `"deep"`, `"ultradeep"`).
+- Anchor format unchanged (`[EXEC:checksum|expert|paradigm|altitude|depth]`).
+- MCP server schema unchanged.
+
+### Deferred to 5.1.0
+
+- MCP server `anthropic` SDK integration with prompt caching and `effort` mapping.
+- Consolidation of duplicate `expert_guidance` dicts
+  (`hooks/cognitive_hook.py` and `claude_code_hook.py` have drifted).
+- Per-expert temperature config audit in `framework_orchestrator.py:758-774`
+  (currently dict metadata only; never reaches an API call).
+
+## [5.0.2] - 2026-02-XX
+
+CHANGELOG entry added retroactively in 5.0.3.
+
+### Changed
+
+- Version bump in `pyproject.toml`. Details lost — no contemporaneous entry.
+
+## [5.0.1] - 2026-01-26
+
+CHANGELOG entry added retroactively in 5.0.3 (per `ADVANCEMENT_ROADMAP.md`).
+
+### Added
+
+- Property-based testing with Hypothesis (22 tests).
+- MCP server package (`orchestra-mcp`, v1.0.0).
+- Context engineering alignment documentation.
+- Fuzz testing with Hypothesis (7 tests; Atheris on Linux CI).
+- Semgrep determinism rules — 9 rules in `.semgrep/orchestra-determinism.yaml`
+  (unseeded random, dict-iteration-unsorted, json.dumps-no-sort-keys, time-in-routing,
+  state-mutation-without-batch, set-iteration, async-gather-unordered,
+  thinking-depth-bypass, burnout-override).
+- Code coverage in CI (50% threshold, Codecov integration).
+- PyPI publish workflows (`cognitive-orchestra` and `orchestra-mcp`).
+- PR automation workflow with Semgrep differential review.
+
 ## [5.0.0] - 2026-01-26
 
 ### Added

README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/v5.0.1-Production%2FStable-success" alt="Production"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/v5.0.3-Production%2FStable-success" alt="Production"></a>
   <a href="tests/"><img src="https://img.shields.io/badge/tests-777%20passed-brightgreen" alt="Tests"></a>
   <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License"></a>
@@ -78,32 +78,21 @@ That's it. Every message now passes through the cognitive engine.
 
 Every message you send to Claude Code:
 
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ PHASE 1: DETECT                                                             │
-│   PRISM extracts signals: emotional > mode > domain > task                  │
-└───────────────────────────┬─────────────────────────────────────────────────┘
-                            ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ PHASE 2: CASCADE                                                            │
-│   Safety gates + Cognitive Safety MoE routing (7 experts, first-match-wins) │
-└───────────────────────────┬─────────────────────────────────────────────────┘
-                            ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ PHASE 3: LOCK                                                               │
-│   MAX3 bounded reflection + cognitive safety gating + deterministic checksum│
-└───────────────────────────┬─────────────────────────────────────────────────┘
-                            ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ PHASE 4: EXECUTE                                                            │
-│   Claude generates response with locked parameters                          │
-│   Anchor: [EXEC:a3f2b8|direct|Cortex|30000ft|standard]                      │
-└───────────────────────────┬─────────────────────────────────────────────────┘
-                            ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ PHASE 5: UPDATE                                                             │
-│   RC^+xi convergence tracking → attractor basins                            │
-└─────────────────────────────────────────────────────────────────────────────┘
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#1F2937','primaryTextColor':'#F5F1EA','primaryBorderColor':'#1F2937','lineColor':'#1F2937','secondaryColor':'#F5F1EA','tertiaryColor':'#F5F1EA','fontFamily':'system-ui, -apple-system, sans-serif'}}}%%
+flowchart TD
+    In(["User message to Claude Code"])
+    A["<b>1 · DETECT</b><br/>PRISM signal extraction<br/>emotional → mode → domain → task"]
+    B["<b>2 · CASCADE</b><br/>Safety gates + 7-expert MoE<br/>first-match-wins"]
+    C["<b>3 · LOCK</b><br/>MAX3 reflection · safety gate<br/>deterministic checksum"]
+    D["<b>4 · EXECUTE</b><br/>Locked-parameter generation<br/>EXEC:checksum · expert · paradigm · altitude · depth"]
+    E["<b>5 · UPDATE</b><br/>RC^+ξ convergence tracking<br/>attractor basins"]
+    Out(["Response + persisted state"])
+    In --> A --> B --> C --> D --> E --> Out
+    classDef phase fill:#1F2937,stroke:#1F2937,color:#F5F1EA,stroke-width:0px
+    classDef io fill:#F5F1EA,stroke:#1F2937,color:#1F2937,stroke-width:2px
+    class A,B,C,D,E phase
+    class In,Out io
 ```
 
 ---
@@ -142,6 +131,32 @@ The system protects you from yourself:
 
 ---
 
+## Burnout Escalation
+
+Cognitive state moves between four levels. Escalation tracks observable signals; recovery is always available and is body-first, not productivity-driven.
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#1F2937','primaryTextColor':'#F5F1EA','primaryBorderColor':'#1F2937','lineColor':'#1F2937','fontFamily':'system-ui, -apple-system, sans-serif'}}}%%
+stateDiagram-v2
+    direction LR
+    [*] --> GREEN
+    GREEN --> YELLOW: typos rising,<br>shorter messages
+    YELLOW --> ORANGE: frustration,<br>declining coherence
+    ORANGE --> RED: ALL CAPS,<br>spiral, incoherence
+    YELLOW --> GREEN: rest, water, break
+    ORANGE --> GREEN: walk, family,<br>body-first
+    RED --> GREEN: full stop,<br>body-first protocol
+
+    classDef calm fill:#F5F1EA,stroke:#1F2937,color:#1F2937,stroke-width:2px
+    classDef alert fill:#1F2937,stroke:#1F2937,color:#F5F1EA,stroke-width:0px
+    class GREEN calm
+    class YELLOW,ORANGE,RED alert
+```
+
+Recovery from RED is always **body before brain**: water, walking, family, outside — then back to work when (and only when) the body says so.
+
+---
+
 ## CLI Commands
 
 ```bash
@@ -252,7 +267,7 @@ Orchestra/
 │   ├── test_parameter_locker.py   # Safety gating
 │   ├── test_otel_adapter.py       # Observability
 │   └── ...                        # Integration, chaos, resilience
-└── pyproject.toml                 # v5.0.1
+└── pyproject.toml                 # v5.0.3
 ```
 
 ---
@@ -308,7 +323,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 ---
 
-*Orchestra v5.0.1 - Cognitive Engine for Claude Code*
+*Orchestra v5.0.3 - Cognitive Engine for Claude Code*
 
 [![PyPI](https://img.shields.io/pypi/v/cognitive-orchestra)](https://pypi.org/project/cognitive-orchestra/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

THINKINGMACHINES_COMPLIANCE.md

@@ -23,6 +23,32 @@ Orchestra demonstrates **STRONG** batch-invariance compliance with a few minor v
 
 ---
 
+## Scope of Determinism
+
+*Added in v5.0.3.* This section clarifies what Orchestra's "He2025 compliance" claim actually covers — and what it doesn't.
+
+### What IS deterministic
+
+- **Routing decisions** — signal detection (PRISM) → expert selection (MoE) → locked parameters. Given identical state and input, Orchestra produces identical routing every time.
+- **Routing checksum** — the 6-character hex checksum in `LockedParams` is batch-invariant per [He2025]. It excludes `reflection_iteration` by design so the same routing decision yields the same checksum across MAX3 reflection cycles.
+- **Persisted cognitive state** — atomic writes via `file_ops.atomic_write_json()` with `sort_keys=True`. Same state → same on-disk bytes.
+- **Anchor format** — `[EXEC:checksum|expert|paradigm|altitude|depth]` is constructed by a single function (`LockedParams.to_anchor()`) and the field count is contract.
+
+### What IS NOT deterministic
+
+- **Claude's response text.** The Anthropic API does not guarantee bitwise reproducibility, particularly under adaptive thinking (`thinking: {type: "adaptive"}`) which is the only on-mode on Opus 4.7. Tests that assert on exact response strings will be flaky by design.
+- **Wall-clock timestamps** in observability logs.
+- **Compaction outputs** (when context compaction is enabled — beta on Opus 4.7).
+- **Token counts.** Opus 4.7 counts tokens differently from Opus 4.6 for the same input; do not assume `count_tokens()` results are stable across model versions.
+
+### What this means in practice
+
+Orchestra's anchor provides **session continuity and routing reproducibility**, not bit-for-bit output reproducibility. The He2025 batch-invariance claim is about Orchestra's kernel selection (which expert fires, which params get locked), not about what Claude says in response.
+
+If you're building tests that need to compare Claude's output across runs, use Orchestra's checksum for routing identity. Do not assert on response text — use structural or semantic checks instead.
+
+---
+
 ## Compliance Analysis
 
 ### COMPLIANT Components

src/orchestra/__init__.py

@@ -54,7 +54,7 @@
     FO_LOG_LEVEL - DEBUG, INFO, WARNING, ERROR
 """
 
-__version__ = "5.0.1"
+__version__ = "5.0.3"
 __author__ = "Framework Ecosystem Integration"
 
 # Core orchestrator
@@ -121,9 +121,9 @@
     get_logger,
     JSONFormatter,
     TextFormatter,
     log_execution,
     log_orchestration_start,
     log_orchestration_complete,
 )
 
 # Health checks
@@ -150,10 +150,10 @@
     validate_principles,
     validate_state_file,
     validate_agent_result,
     DOMAIN_CONFIG_SCHEMA,
     PRINCIPLES_SCHEMA,
     STATE_FILE_SCHEMA,
     AGENT_RESULT_SCHEMA,
 )
 
 # ============================================================================
@@ -356,6 +356,7 @@
     LockResult,
     ParameterLocker,
     DEPTH_BUDGETS,
+    DEPTH_TO_EFFORT,
     create_locker,
 )
 
@@ -655,6 +656,7 @@
     "LockResult",
     "ParameterLocker",
     "DEPTH_BUDGETS",
+    "DEPTH_TO_EFFORT",
     "create_locker",
 
     # Convergence Tracker (RC^+xi)

src/orchestra/claude_code_hook.py

@@ -142,15 +142,18 @@ def build_guidance(result: NexusResult) -> str:
     trigger = result.routing.trigger
     paradigm = result.lock.params.paradigm
 
-    # Expert-specific guidance
+    # Expert-specific guidance.
+    # v5.0.3: softened for Opus 4.7's stricter literal-instruction-following.
+    # All-caps imperatives ("EMPATHY FIRST", "BREAK DOWN", etc.) overtriggered
+    # on 4.7. Conditional phrasing ("when X, do Y") is the recommended pattern.
     expert_guidance = {
-        "validator": "EMPATHY FIRST. Acknowledge the struggle. Normalize difficulty. Do not immediately try to solve.",
-        "scaffolder": "BREAK DOWN the task. Provide structure. Reduce scope if needed. One small step at a time.",
-        "restorer": "EASY WINS mode. Suggest simple tasks. Rest is OK. Recovery without guilt.",
-        "refocuser": "GENTLE REDIRECT. Acknowledge the tangent, then guide back to the goal.",
-        "celebrator": "ACKNOWLEDGE THE WIN. Provide dopamine boost. Celebrate before moving on.",
-        "socratic": "GUIDE DISCOVERY. Follow threads. Ask questions. Let them explore.",
-        "direct": "MINIMAL FRICTION. Stay out of the way. Direct execution."
+        "validator": "Lead with empathy. Acknowledge the difficulty before suggesting solutions.",
+        "scaffolder": "Break the task into smaller steps. Offer structure when scope is unclear.",
+        "restorer": "Suggest a lighter task or a pause. Recovery is part of the work.",
+        "refocuser": "Acknowledge the tangent briefly, then return to the original goal.",
+        "celebrator": "Acknowledge the win with a short, specific recognition.",
+        "socratic": "Offer questions that help discovery. Follow promising threads.",
+        "direct": "Stay direct. Minimal friction. Execute.",
     }
 
     guidance = expert_guidance.get(expert, "Proceed with standard response.")

src/orchestra/parameter_locker.py

@@ -47,14 +47,27 @@ class ThinkDepth(Enum):
     ULTRADEEP = "ultradeep"  # 128K tokens (Opus only)
 
 
-# Depth budgets
+# Depth budgets (legacy — designed for Opus 4.5/4.6 `thinking.budget_tokens`).
+# Retained for backward compatibility; downstream consumers may still import this.
 DEPTH_BUDGETS = {
     ThinkDepth.MINIMAL: 1_000,
     ThinkDepth.STANDARD: 8_000,
     ThinkDepth.DEEP: 32_000,
     ThinkDepth.ULTRADEEP: 128_000
 }
 
+# Opus 4.7+ vocabulary alignment (added v5.0.3).
+# Maps Orchestra's depth tiers to Anthropic's `output_config.effort` levels.
+# On Opus 4.7, `thinking.budget_tokens` is removed (400 error); `effort` is the
+# correct knob. `xhigh` is new on 4.7 — recommended default for coding/agentic
+# work and used by Claude Code itself.
+DEPTH_TO_EFFORT = {
+    ThinkDepth.MINIMAL:   "low",
+    ThinkDepth.STANDARD:  "medium",
+    ThinkDepth.DEEP:      "high",
+    ThinkDepth.ULTRADEEP: "xhigh",
+}
+
 
 # =============================================================================
 # Paradigms

tests/test_parameter_locker.py

@@ -24,6 +24,7 @@
     LockResult,
     ParameterLocker,
     DEPTH_BUDGETS,
+    DEPTH_TO_EFFORT,
     create_locker,
 )
 from orchestra.expert_router import Expert, RoutingResult
@@ -48,6 +49,32 @@ def test_depth_budgets(self):
         assert DEPTH_BUDGETS[ThinkDepth.ULTRADEEP] == 128_000
 
 
+class TestDepthToEffort:
+    """v5.0.3: Opus 4.7 vocabulary alignment.
+
+    DEPTH_TO_EFFORT maps Orchestra's depth tiers to Anthropic's
+    `output_config.effort` levels. On Opus 4.7, `thinking.budget_tokens`
+    is removed (400 error); `effort` is the correct knob.
+    """
+
+    def test_effort_mapping(self):
+        """Should map each ThinkDepth tier to the correct effort level."""
+        assert DEPTH_TO_EFFORT[ThinkDepth.MINIMAL] == "low"
+        assert DEPTH_TO_EFFORT[ThinkDepth.STANDARD] == "medium"
+        assert DEPTH_TO_EFFORT[ThinkDepth.DEEP] == "high"
+        assert DEPTH_TO_EFFORT[ThinkDepth.ULTRADEEP] == "xhigh"
+
+    def test_legacy_budgets_still_exported(self):
+        """v5.0.3 is an additive change — DEPTH_BUDGETS must stay on public API."""
+        from orchestra import DEPTH_BUDGETS as legacy_budgets
+        assert legacy_budgets[ThinkDepth.STANDARD] == 8_000
+
+    def test_new_mapping_publicly_exported(self):
+        """DEPTH_TO_EFFORT should be importable from orchestra top-level."""
+        from orchestra import DEPTH_TO_EFFORT as effort_map
+        assert effort_map[ThinkDepth.ULTRADEEP] == "xhigh"
+
+
 class TestParadigm:
     """Test Paradigm enum."""