v5.0.3 — Opus 4.7 vocabulary alignment + mermaid diagrams

[JosephOIbrahim]

Summary

Two-commit PR migrating Orchestra's internal vocabulary from thinking.budget_tokens (Opus 4.5/4.6) to output_config.effort (Opus 4.7), plus a docs refresh replacing ASCII diagrams with mermaid.

Commit 1 — feat: v5.0.3 — Opus 4.7 vocabulary alignment (fb97d7c)

• Added DEPTH_TO_EFFORT mapping in parameter_locker.py (MINIMAL→"low", STANDARD→"medium", DEEP→"high", ULTRADEEP→"xhigh"). Exported from orchestra top-level. On Opus 4.7, thinking.budget_tokens returns 400; effort is the correct knob.
• Softened all-caps imperatives in claude_code_hook.py expert_guidance ("EMPATHY FIRST." → "Lead with empathy.", etc.) for Opus 4.7's stricter literal-instruction-following. Routing behavior unchanged.
• Added "Scope of Determinism" section to THINKINGMACHINES_COMPLIANCE.md distinguishing Orchestra's batch-invariant routing (deterministic per He2025) from Claude API output (not deterministic under adaptive thinking).
• Retroactive CHANGELOG entries for 5.0.1 + 5.0.2 (entries were missing).
• 3 new tests in TestDepthToEffort.

Non-breaking: DEPTH_BUDGETS stays exported, ThinkDepth enum values unchanged, anchor format unchanged, MCP schema unchanged.

Commit 2 — docs: replace ASCII pipeline with mermaid + add burnout state diagram (be587d3)

• 5-phase NEXUS pipeline ASCII → mermaid flowchart (two-tone: charcoal phases, cream I/O boundaries)
• New "Burnout Escalation" subsection with mermaid stateDiagram-v2 (cream = calm, charcoal = alert)
• Renders on GitHub light + dark themes

Verification

• ✅ 797 tests pass (+ 3 new TestDepthToEffort), 5 skipped (OTel optional)
• ✅ He2025 batch-invariance tests intact
• ✅ Anchor format [EXEC:checksum|expert|paradigm|altitude|depth] (5 fields) preserved
• ✅ Determinism spot-check: two fresh orchestrators → identical checksum 6bb68d
• ✅ Public API: DEPTH_BUDGETS + DEPTH_TO_EFFORT + ThinkDepth all importable
• ✅ Zero new semgrep findings in edited files

Test plan

• CI green on test-status check
• Mermaid diagrams render correctly in GitHub PR preview (light + dark themes)
• pip install -e . from clean checkout works
• orchestra status runs

Deferred to v5.1.0

• MCP server anthropic SDK integration with prompt caching + effort mapping
• Consolidation of duplicate expert_guidance dicts (hooks/cognitive_hook.py ↔ claude_code_hook.py)
• Per-expert temperature config audit in framework_orchestrator.py

Deferred to v5.0.4 cleanup

• Version refs in CONTRIBUTING.md, CITATIONS.md, docs/QUICKSTART.md, ADVANCEMENT_ROADMAP.md, docs/USD_COGNITIVE_SUBSTRATE_V5.md (still say 5.0.1)
• Duplicate determinism docs in docs/ (root is canonical)
• Dashboard StatusView.jsx label semantics (budget: '1K' → effort: 'low')

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added DEPTH_TO_EFFORT parameter mapping for specifying model effort levels across depth tiers.

• Documentation

  • Introduced "Burnout Escalation" section documenting cognitive state levels and recovery transitions.
  • Added "Scope of Determinism" clarification on routing determinism guarantees and non-deterministic components.
  • Updated architecture diagrams with Mermaid flowchart visualization.

• Improvements

  • Softened guidance phrasing for expert roles to improve instruction compatibility.
  • Version bumped to 5.0.3 with Opus 4.7 alignment.

[coderabbitai]

📝 Walkthrough

Walkthrough

Version 5.0.3 introduces a DEPTH_TO_EFFORT constant that maps Orchestra depth tiers to Anthropic effort strings, exports it from the top-level package, softens expert guidance phrasing for Opus 4.7 compatibility, and updates release documentation including determinism scope clarification and visual diagrams.

Changes

v5.0.3 Release: DEPTH_TO_EFFORT and Opus 4.7 Alignment

Layer / File(s)	Summary
DEPTH_TO_EFFORT constant definition and export src/orchestra/parameter_locker.py, src/orchestra/__init__.py, tests/test_parameter_locker.py	DEPTH_TO_EFFORT maps ThinkDepth tiers to Anthropic effort strings (ULTRADEEP → "xhigh"), DEPTH_BUDGETS documentation is expanded for clarity, package version bumps to 5.0.3, and the constant is exported from the top-level package. Tests validate the mapping, legacy DEPTH_BUDGETS availability, and top-level import accessibility.
Opus 4.7 guidance softening src/orchestra/claude_code_hook.py	Expert role guidance templates in build_guidance() replace all-caps imperatives with conditional phrasing to accommodate Opus 4.7's stricter instruction-following, with v5.0.3 explanatory comments.
Release documentation updates CHANGELOG.md, README.md, THINKINGMACHINES_COMPLIANCE.md	CHANGELOG documents the 5.0.3 release with DEPTH_TO_EFFORT alignment and Opus 4.7 guidance changes; README updates version badge, footer, and replaces ASCII phase diagram with Mermaid flowchart; adds Burnout Escalation state-transition diagram; THINKINGMACHINES_COMPLIANCE adds Scope of Determinism section clarifying what Orchestra determinism covers and guidance for test assertions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

A rabbit hops through version three,
DEPTH_TO_EFFORT for clarity—
Burnout states shown, green to red,
Softer guidance, peace of mind spread. 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: version bump to 5.0.3, Opus 4.7 vocabulary alignment (DEPTH_TO_EFFORT mapping), and mermaid diagram updates.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/v5.0.3-opus-4.7-vocabulary

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

PR Analysis Summary

Changed files: 7

Checks

• Tests passed
• Semgrep determinism check

ThinkingMachines [He2025] Compliance

• Fixed evaluation order: ✅
• Batch-invariance: ✅

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/orchestra/parameter_locker.py (1)

432-436: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add DEPTH_TO_EFFORT to __all__.

DEPTH_TO_EFFORT is imported and re-exported from __init__.py (line 359) and included in the top-level __all__ (line 659), but it's missing from this module's __all__ export list. For consistency and discoverability, add it here alongside DEPTH_BUDGETS.

📦 Proposed fix to add DEPTH_TO_EFFORT to __all__

 __all__ = [
     'ThinkDepth', 'Paradigm', 'LockStatus',
     'LockedParams', 'LockResult', 'ParameterLocker',
-    'DEPTH_BUDGETS', 'create_locker'
+    'DEPTH_BUDGETS', 'DEPTH_TO_EFFORT', 'create_locker'
 ]

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/orchestra/parameter_locker.py` around lines 432 - 436, The module-level
__all__ is missing DEPTH_TO_EFFORT — update the __all__ list in
parameter_locker.py to include 'DEPTH_TO_EFFORT' alongside 'DEPTH_BUDGETS' so
the symbol is exported; locate the __all__ definition that currently lists
'DEPTH_BUDGETS' and add 'DEPTH_TO_EFFORT' to that list.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/orchestra/parameter_locker.py`:
- Around line 432-436: The module-level __all__ is missing DEPTH_TO_EFFORT —
update the __all__ list in parameter_locker.py to include 'DEPTH_TO_EFFORT'
alongside 'DEPTH_BUDGETS' so the symbol is exported; locate the __all__
definition that currently lists 'DEPTH_BUDGETS' and add 'DEPTH_TO_EFFORT' to
that list.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 941fb8cd-445d-4d26-9d02-4f472eec6e10

📥 Commits

Reviewing files that changed from the base of the PR and between 61b7141 and be587d3.

📒 Files selected for processing (7)

• CHANGELOG.md
• README.md
• THINKINGMACHINES_COMPLIANCE.md
• src/orchestra/__init__.py
• src/orchestra/claude_code_hook.py
• src/orchestra/parameter_locker.py
• tests/test_parameter_locker.py