docs: correct orchestrator invocation and timeout guarantees

[groupthinking]

Description

The original documentation is already present on master; before this update, this PR had an empty diff. This follow-up addresses all eight existing inline review findings in docs/orchestrator_mapreduce.md.

• Explain that zero-argument protocols ignore inputs and parameterized protocols receive the full dict, without filtering extra keys.
• Identify the parameterized health-checker example as illustrative; the existing protocol takes no arguments.
• Clarify that timeout marks a subtask failed but does not terminate its running thread, and timeout outcomes are not sent to track_outcome.
• Label both diagram code fences as text.

Type of change

• Documentation update

Verification

• Reviewed all eight findings against the current implementation.
• Nine local checks passed using the actual orchestrator with local protocol fixtures: Markdown fence validation, existing protocol signature, argument dispatch, defaults, signature errors and tracking, success tracking, timeout without tracking, and worker continuation after timeout.
• git diff --check passed. Documentation corrections plus formatting-only changes to orchestrator_mapreduce.py.
• Full pytest: collection blocked by missing mcp and psycopg2 dependencies.
• black --check . passed after formatting orchestrator_mapreduce.py: all 83 Python files unchanged. Complete Python AST equality before/after formatting passed.
• flake8: unavailable in this workspace.

Additional context

No runtime behavior changed; the Python edit preserves the complete AST. The nine checks used local fixtures and did not call external services. The initial verification harness had an import-path error after changing temporary directories; importing the loader before the directory change fixed the harness and the rerun passed.

Shell git push failed due to missing HTTPS credentials. The verified file was published through the authenticated GitHub connector in commit f051104. This PR is being completed under the user's explicit write/push/merge request.

Formatting correction published as 042c24f, addressing the Black CI failure supplied by the user. Remote CI results must be checked on this latest head.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 9c68ce1d-dc5e-470c-a11b-e730c54468d5

Summary by CodeRabbit

• Documentation
  • Added extensive documentation for the orchestrator module including detailed coverage of system architecture, orchestration design patterns, complete API reference with code examples, practical usage scenarios from basic to advanced, guidance for customizing and extending functionality, comprehensive error handling and recovery documentation, state persistence information, memory optimization strategies, and integration guidelines for connecting with other system components.

Walkthrough

Adds docs/orchestrator_mapreduce.md, a 571-line reference document for the orchestrator_mapreduce module. The document covers the public API (__all__), data models (TaskStatus, SubTask, OrchestratedJob), HierarchicalOrchestrator constructor and lifecycle methods, customization contracts, protocol calling conventions via inspect.signature(), state persistence to STATE.md, failure tiers, usage examples, integration points, configuration reference, a lifecycle diagram, and a v1.0.0 changelog entry.

Changes

HierarchicalOrchestrator Documentation

Layer / File(s)	Summary
Module identity, public API, and data models docs/orchestrator_mapreduce.md	Documents module dependencies and __all__ exports alongside TaskStatus states and SubTask/OrchestratedJob field shapes.
Constructor and lifecycle methods docs/orchestrator_mapreduce.md	Documents HierarchicalOrchestrator constructor parameters and the run/plan/map_execute/reduce_verify methods, including bounded concurrency, per-subtask timeouts, retry/mutation loop, escalation, and STATE.md persistence. Includes the lifecycle flow diagram.
Customization contracts and protocol calling conventions docs/orchestrator_mapreduce.md	Documents the verification_gate return contract and reducer interface with worked examples; describes three task() calling conventions resolved via inspect.signature().
Persistence, failure tiers, and memory management docs/orchestrator_mapreduce.md	Documents STATE.md audit append behavior, the three-tier failure strategy (retry/escalate/timeout), and max_job_history pruning during plan().
Usage examples, integration, configuration, and changelog docs/orchestrator_mapreduce.md	Provides minimal through step-by-step usage examples; integration with protocols.loader, agents.mutator, utils.tracker, utils.logger; parameter configuration reference with tuning guidance; and v1.0.0 changelog entry.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• groupthinking/self-correcting-executor#114: Introduces the orchestrator_mapreduce.py implementation that this documentation directly describes, including HierarchicalOrchestrator, SubTask, OrchestratedJob, and the Plan→Map→Reduce lifecycle.

Suggested labels

documentation

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description check	✅ Passed	The description clearly summarizes the documentation corrections, identifies the documentation update type, records verification results, and provides relevant context. It does not include an issue re…
Title check	✅ Passed	The title is concise, specific, and directly describes the documented corrections for orchestrator invocation and timeout behavior.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/orchestrator-mapreduce

---

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

_{🗺️ The plan divides, the map fans wide,
Subtasks race with bounded stride,
A gate inspects each reduced result—
Retry, mutate, or humans consult.
STATE.md holds the audit trail,
In quantum steps, no task shall fail! ⚛️}

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

[Copilot]

Pull request overview

Adds a new, comprehensive Markdown document describing the orchestrator_mapreduce.py module (Plan → Map → Reduce flow, public API/classes, customization points, protocol calling behavior, persistence, and examples) to help developers integrate and extend the orchestrator.

Changes:

• Introduces full module documentation for orchestrator_mapreduce.py in docs/orchestrator_mapreduce.md.
• Adds architecture/lifecycle diagrams, API reference, customization contracts, and usage examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

🤖 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.

Inline comments:
In `@docs/orchestrator_mapreduce.md`:
- Line 21: The fenced code block at line 21 in the orchestrator_mapreduce.md
file is missing a language identifier, which violates the MD040 markdown linting
rule. Add the language identifier `text` immediately after the opening triple
backticks on the line containing the fenced code block start marker to specify
that this is a text/ASCII art block, ensuring compliance with markdown
standards.
- Line 520: The fenced code block at line 520 in the orchestrator_mapreduce.md
file is missing a language identifier, which violates the MD040 Markdown linting
rule. Add the language identifier `text` to the opening of the fenced code block
(the line with the opening triple backticks) since this contains an ASCII
diagram. Change the opening ``` to ```text to specify that the content is plain
text.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1cc1a810-26b5-4476-a2fa-6f3e527537c5

📥 Commits

Reviewing files that changed from the base of the PR and between 1637fd3 and 2a5099a.

📒 Files selected for processing (1)

• docs/orchestrator_mapreduce.md

[groupthinking]

Gtg

[Copilot]

🟡 Changes recommended

Resolve the two remaining documentation inconsistencies.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

docs/orchestrator_mapreduce.md:185

• This new clarification conflicts with the lifecycle diagram, which still shows Apply timeout followed unconditionally by Track outcome. A reader can therefore still infer that timed-out subtasks are tracked, contrary to the implementation and the text here; update the diagram to show tracking only for successful returns and non-timeout exceptions.

- Tracks successful returns and non-timeout exceptions via `track_outcome()` (non-blocking, via `run_in_executor`); timeout failures are not sent to this tracker

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Lite

[groupthinking]

@copilot Fix the code for all comments in this review comment.

When a review comment includes a suggested change, apply the suggestion exactly.

Do not make changes beyond what is described in the linked review comment.

[Copilot]

Addressed in a2d17ae.

[Copilot]

🔵 Needs a closer look

Update the remaining examples that pass inputs to the zero-argument health checker.

Review details

Suppressed comments (1)

docs/orchestrator_mapreduce.md:289

• This clarification still leaves the runnable endpoint examples above (lines 148–149) and in the fan-out section (lines 392–394) using api_health_checker with per-endpoint inputs. That protocol is zero-argument, so _run_protocol_isolated() ignores those values and the examples do not validate the listed endpoints. Update both examples to use the separate parameterized protocol named by this section, or remove the per-endpoint inputs and describe the existing checker’s behavior.

The repository's existing `api_health_checker.task()` takes no arguments and checks its own endpoint list. To use the parameterized examples, implement a separate protocol like the following and use its name in `task_list`:

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Lite