# Orchestrator State > Orchestrator-state remediation-cycle and human-interaction invariants. - Skill: `drmoisan/orchestrator-state` (Agent Skill) - Install (CLI): `npx skillmds@latest add drmoisan/orchestrator-state` - Raw SKILL.md: https://api.skillmd.com/api/skills/drmoisan/orchestrator-state/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: drmoisan (https://skillmd.com/u/drmoisan) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/drmoisan/orchestrator-state --- # Converted rule Source: legacy Claude rule `orchestrator-state`. # Orchestrator-State Remediation-Cycle and Human-Interaction Invariants This rule governs remediation-cycle records and the optional `human_interaction` block in the orchestrator-state checkpoint at `artifacts/orchestration/orchestrator-state.json`. It documents three invariants that must hold for each remediation cycle, plus three invariants for the `human_interaction` block, so that resume and review workflows do not depend on a structurally invalid checkpoint. ## Foreign Schema Warning (do not copy verbatim) A hardened snapshot from another repository contains a JSON Schema for the orchestrator-state artifact whose `$id` references a foreign origin (`drmoisan.github.io/mix-calculator/`). That schema MUST NOT be copied verbatim into this repository: its `$id`, its top-level required-field set, and its cycle-level `additionalProperties: false` do not match this repository's checkpoint contract. The invariants below are re-expressed here as prose and enforced by validator logic in `scripts/dev_tools/validate_orchestrator_state.py`, not by importing a foreign schema file. This prohibition is specific to the disqualified foreign schema identified by the `drmoisan.github.io/mix-calculator/` `$id`. A schema whose `$id` is repo-local and whose required-field set and `additionalProperties` policy match this repository's checkpoint contract is not the disqualified foreign artifact; even so, the repository's enforcement mechanism remains the Python validator prose-and-logic above, not an imported schema file. ## Portable Handoff Projection Invariants A provider-native destination checkpoint materialized from the portable handoff contract must retain the following linkage: - `provider`, `checkpoint_expression`, and `destination_projector` identify the destination expression and selected adapter. - `plan-path` and `next_step` equal the portable envelope's exact plan path and recorded lifecycle transition. The destination must not rediscover a plan or replace either value from local convention. - `portable_handoff` retains the handoff ID, envelope SHA-256, latest history entry SHA-256, adapter identity, source validator, identity and binding fields, source checkpoint/archive facts, exact plan proof, lifecycle, capabilities, and scheduler context. - Historical source receipts remain opaque references under `portable_handoff.source.expression.historical_receipts`. They must not be rewritten as destination-provider receipts. - `destination_evidence` starts as `pending_first_delegation` with an empty receipt list. Destination routing, topology, model, and receipts may be recorded only for the first new delegation after checkpoint materialization. The portable lifecycle permits only the registered state transitions: `legacy_v1` to migration, `preparation_complete` to `prepared_to_atomic_execution`, `validated` to destination materialization, `materialized` to `atomic_execution`, and a bounded scheduled-child return from an authorized child execution phase. An attempted replay of a completed phase is invalid. A failed contract, binding, capability, authority, plan, replay, dirty-worktree, candidate, archive, or replacement check must produce the deterministic blocked result and leave the source checkpoint authoritative. A blocked result must retain the primary `HANDOFF_*` code and affected paths where applicable; it must not record a completed transition or destination delegation. For parallel and epic children, `return_to_scheduler` accepts only a result whose run, item, parent checkpoint path/hash, scheduler owner, child execution owner, return contract, plan hash, child checkpoint hash, and result hash match the envelope. The child may return that bounded result but may not assume cohort or wave ordering, barriers, fan-in, integration, cleanup, or parent completion authority. ## Scope and Backward Compatibility These invariants apply only when the checkpoint contains a top-level `remediation_loop` with a `cycles` array. A checkpoint with no `remediation_loop` (the existing step-based checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive. ## Invariants (per remediation cycle) 1. **Non-empty `plan_path`.** Each cycle's `plan_path` must be a non-empty string. A missing value, a non-string value, or an empty/whitespace-only string is a malformed cycle. 2. **Execution requires cleared preflight.** A cycle's `execution_status` may be in `{in_progress, complete, failed}` only when that cycle's `preflight.final_status` is exactly `'clear'`. Any other preflight status with one of those execution statuses is a malformed cycle (execution was recorded before preflight cleared). 3. **Exit gate requires zero blocking findings.** When a cycle's `exit_condition_met == true`, its `blocking_count` must be `0`. A non-zero `blocking_count` with `exit_condition_met == true` is a malformed cycle (the exit gate was marked satisfied while blocking findings remained). ## Human-Interaction Scope and Backward Compatibility These invariants apply only when the checkpoint contains a top-level `human_interaction` block. A checkpoint with no `human_interaction` key (the existing checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive and support the autonomous-execution mandate documented in `.agents/skills/orchestrate/SKILL.md`. ## Invariants (human_interaction block) 1. **Required `requirements` list.** When `human_interaction` is present, it must be an object containing a `requirements` list. A non-object `human_interaction`, or a `requirements` value that is not a list, is a malformed block. 2. **Per-requirement `response` enum membership.** Each requirement must be an object whose `response` value is one of `scope_change`, `exception`, or `halt`. A requirement that is not an object, or whose `response` is outside this enum, is a malformed requirement. 3. **Exception requires `runbook_path`.** A requirement whose `response == "exception"` must carry a non-empty `runbook_path` string. A missing, non-string, or empty/whitespace-only `runbook_path` on an `exception` requirement is a malformed requirement. ## Enforcement - `scripts/dev_tools/validate_orchestrator_state.py` appends one error per violated invariant when a `remediation_loop` is present, using the existing validator message style (literal, checkpoint-context prefixed). The validator returns a list of error strings and does not mutate its input. - `scripts/dev_tools/validate_orchestrator_state.py` likewise appends one error per violated `human_interaction` invariant when a `human_interaction` key is present, using the same literal, checkpoint-context-prefixed message style. The check does not import or read any schema file. - The validator is consumed by the MCP tool `validate_orchestration_artifacts`; backward compatibility for existing step-based checkpoints is preserved.