feat(#4740): make the Loop Host Contract role partition normative and enforced (#4742)

* test(#4740): pin the per-step role-family partition

Failing-first coverage for the Loop Host Contract role partition. At this
commit crossCheckRoleFamilies does not exist, so the rows throw
"crossCheckRoleFamilies is not a function" -- the RED proof they bind to
behavior rather than restating it.

ADR-894 section 3 assigns roles per step but parenthesises the assignment as
"(illustrative roles)", and nothing enforced it. The only thing standing in the
way was a single deepEqual in this same file, which is editable prose.

Rows cover: each step's own family accepted; a strict subset accepted; a
foreign role rejected at every step; an unknown role rejected; an unknown step
failing CLOSED; capitalization not silently matched; every offending role
reported rather than only the first; and purity, because buildContract puts the
same array into the generated contract.

Two rows exist because an earlier cut of this suite was vacuous. The purity
fixture is deliberately UNSORTED -- an alphabetically-sorted fixture cannot
fail an in-place sort(), and the mutant was being killed by three unrelated
rows instead. A parity row asserts ROLE_FAMILY and ROLE_TO_AGENT cover the
exact same role-name domain, both directions: they are parallel constants over
one domain, so divergence is the generative-fix class CLAUDE.md names.

Every negative row asserts the offending ROLE NAME and the STEP NAME appear in
the message. A count-only assertion survives a mutant that reports the wrong
role, which the 80% Stryker gate would surface only after a full CI round-trip.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(#4740): reject a cross-family agent-role declaration

Orchestration and execution are distinct functions of the loop and must not
drift into one another. That partition was real but unenforced: ADR-894
section 3 calls its own role assignment "illustrative", and the generator
accepted anything. Adding orchestrator to execute-phase.md's agent-roles line
compiled, --check passed once regenerated, and capability-validator.cjs then
began accepting into:"orchestrator" at every execute point.

ROLE_FAMILY maps every role to one of orchestration, planning or execution.
EXPECTED_FAMILY_BY_STEP gives each of the five steps exactly one family.
crossCheckRoleFamilies rejects a cross-family role, a role outside the
vocabulary, and an unknown step. It reports every offender, not the first.

It fails CLOSED on an unknown step, deliberately diverging from
assertPointsCoverage's "unknown step -- caught elsewhere". For points that is
true: the canonical-set and duplicate checks catch it. For roles there is no
second net, so failing open would leave an unknown step as the one input that
bypasses the gate.

crossCheckRoles' orchestrator exemption is untouched. ROLE_TO_AGENT maps roles
to agent FILES and the orchestrator is the host, owning none -- admissibility
and agent-file presence are separate concerns with separate checks.

Additive to section 3's existing rule that contribution.into must be a member
of the step's agentRoles, which is unchanged. That governs what a CAPABILITY
may target; this governs what a WORKFLOW may declare. No capability is
affected, and all five workflows already declare single-family sets, so the
gate is green on the commit that introduces it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(#4740): make the ADR-894 role assignment normative

Section 3 parenthesises its per-step role assignment as "(illustrative roles)".
That word was accurate about the list's PURPOSE -- it illustrated the shape of
a generated contract entry -- and wrong about its STATUS, because the
assignment was load-bearing from the moment the generator consumed it. Read
literally it makes the partition an example rather than a rule.

Appended as a dated in-place section per docs/contributor-standards.md, which
records that an accepted ADR is never rewritten and names this the default
pattern. Section 3's original body is untouched.

The amendment states the three disjoint families, the one family each step
admits, that a step may declare a strict subset but never outside it, and why
this is a clarification rather than a new decision: the contract is generated
from the workflow markers "so it cannot drift into a lie", and all five
workflows have always declared single-family sets. What was absent was any
statement that it is required, and any check that it holds.

It also pins the distinction that is easy to re-merge: contribution.into being
a member of agentRoles governs what a CAPABILITY may target and is unchanged;
the family rule governs what a WORKFLOW may declare. The CONTEXT.md glossary
entry for the Loop Host Contract records the same, beside the agent-reference
drift guard it already documented.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#4740): add changeset fragment

pr:0 placeholder is backfilled with the real number once the PR exists.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#4740): backfill changeset pr number

Replaces the pr:0 placeholder with 4742 now that the PR exists. Verified with
GITHUB_BASE_REF=next, the way CI runs them: changeset lint and lint:docs both
go from invalid_pr(0) to ok. Without that env both report success without
evaluating the branch at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#4740): stop injecting the orchestrator procedure into executors

claude-orchestration declared a contribution at execute:wave:pre with
into:"executor". loop-hook-dispatch.md defines a contribution as "inject
fragment.inline verbatim into the context for the role named in into", so its
267 lines were injected into EXECUTOR prompts whenever the capability was
enabled. Those lines are orchestration end to end -- construct a wave manifest,
resolve the dispatch backend, invoke the Workflow tool to spawn executors,
bridge per-agent results into the merge chain. An executor can act on none of
it.

Retargeting to into:"orchestrator" would not have been a fix. ROLE_TO_AGENT
carries no orchestrator entry by design: the orchestrator IS the host, and the
host's procedure lives in execute-phase.md. A step's agentRoles enumerates
agents a capability may inject context INTO, so adding orchestrator there would
model the host as an injectable agent -- the same category error pointed the
other way, and it would need an exception carved into the partition the same
issue just made normative.

So the defect is the mechanism, not the label. A contribution injects into an
agent's context; "replace step 3's inline dispatch loop" is a change to what
the HOST does. The contribution channel was serving as a host-behaviour
directive because it was the only channel available at an execute point.

The entry is removed. plan:post into:"planner" is correct and untouched. The
procedure is preserved verbatim at docs/workflow-backend-dispatch.md inside the
capability -- it is the only copy in the repo -- and is no longer injected
anywhere.

Consequence, not softened: the Workflow backend now has no loop wiring.
Detection, emission and config remain and the design is intact, but nothing
dispatches it. Under the separation ADR-1143 itself asserts it never had a
legitimate channel; ADR-1143's own audit already records the end-to-end path
has never been exercised. Wiring it properly needs a host-level mechanism that
does not exist today.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#4740): invert the stale execute:wave:pre registry assertions

Removing the contribution left four surfaces asserting or describing the old
state. Caught by an isolated review before a verification run was spent, which
is the point of reviewing first: the first of these was a guaranteed CI red.

execute-wave-post-gate-pipeline-e2e asserted against the REAL generated
registry that byLoopPoint['execute:wave:pre'] held exactly one contribution
with capId claude-orchestration. It now holds zero. Inverted to assert exactly
0 -- not a vague >= 0 -- and the #2285 comment above it now explains the
current state rather than the one it was written for.

CONTEXT.md's Claude Orchestration entry claimed two contributions at wired
points. It is now one, and the entry's execute:wave:post label was already
wrong before this change: the manifest said execute:wave:pre. Rewritten to one
plan:post contribution, why the execute-point one was removed, and where the
procedure now lives.

One assertion in claude-orchestration.test.cjs could not fail. It tested for
the prose "(into the executor)" while the doc says "(`into: executor`)", so no
plausible wording matched it and the paired plan:post assertion was carrying
the row. Replaced with a check on the structural claim, and proved RED by
restoring the two-contribution wording before reverting.

The moved procedure keeps section headings that speak as a live contribution --
"When this contribution is active", "Why execute:wave:pre". Preserving the body
verbatim was deliberate, so the headings stay and an editor's note under the
header explains why they read that way.

A sweep of all 17 files referencing byLoopPoint found no further siblings: the
remaining hits are a synthetic capability fixture and an empty-points test that
already expected no active hooks, both correct before and after.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

.changeset/sturdy-elks-march.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 4742
+---
+**A workflow can no longer declare a loop-host agent role belonging to another step family** — the Loop Host Contract assigns each of the five loop steps a role family (orchestration, planning, execution), but nothing enforced it: adding `orchestrator` to an execute step `agent-roles` line compiled cleanly, and capability contributions could then target the orchestrator at execution points. Contract generation now rejects a cross-family role, a role outside the vocabulary, and an unknown step, reporting every offender rather than the first. No existing workflow or capability changes. (#4740)

CONTEXT.md

@@ -357,7 +357,7 @@ Projects a pure, typed install plan for a given runtime by composing artifact pl
 A bundle delivering one optional GSD feature, toggled as a unit at install or after install. Owns its skills, agents, hooks, federated config-key schema (keys + defaults + validation), and loop extension-point registrations, plus a `requires` list of other Capabilities, plus an optional `activationKey` (a dotted config key, e.g. `graphify.enabled`) naming the config toggle that gates the whole capability — consumed by the Capability State Resolver's per-capability `active` (absent → no config gate; see Capability State Resolver tri-state deepening). Declared co-located in the Capability's own folder and compiled into a generated central Capability Registry at build time. The five-step loop (Discuss → Plan → Execute → Verify → Ship) and shared-infrastructure skills (phase, config, help, update, surface, progress) are the privileged host, not Capabilities, in v1 — but host extension points are data so a loop step can become a Capability under a future uniform kernel. Supersedes the implicit feature-scattering across clusters, install-profiles, and config-schema. Generalizes the Skill Surface Budget Module and Runtime Install Policy Module.
 
 ### Loop Host Contract
-Generated description of what the five-step loop (Discuss → Plan → Execute → Verify → Ship) exposes as extension points: per-step loop points, agent roles, and core artifacts. Sourced from structured `<!-- gsd:loop-host ... -->` HTML-comment markers embedded near the top of each of the five step workflow files (`discuss-phase.md`, `plan-phase.md`, `execute-phase.md`, `verify-work.md`, `ship.md`). Generated by `scripts/gen-loop-host-contract.cjs` → `gsd-core/bin/lib/loop-host-contract.cjs` (ADR-894 §3 phase 3a-impl-2). Covers exactly the 12 canonical points (discuss:pre/post, plan:pre/post, execute:pre/wave:pre/wave:post/post, verify:pre/post, ship:pre/post). The generator enforces a drift guard: every declared non-orchestrator agent role must correspond to an actual agent reference in the workflow file. Consumed by `gen-capability-registry.cjs` (replaces the former inline `LOOP_HOST_CONTRACT` constant). Run `node scripts/gen-loop-host-contract.cjs --write` after editing a workflow step marker.
+Generated description of what the five-step loop (Discuss → Plan → Execute → Verify → Ship) exposes as extension points: per-step loop points, agent roles, and core artifacts. Sourced from structured `<!-- gsd:loop-host ... -->` HTML-comment markers embedded near the top of each of the five step workflow files (`discuss-phase.md`, `plan-phase.md`, `execute-phase.md`, `verify-work.md`, `ship.md`). Generated by `scripts/gen-loop-host-contract.cjs` → `gsd-core/bin/lib/loop-host-contract.cjs` (ADR-894 §3 phase 3a-impl-2). Covers exactly the 12 canonical points (discuss:pre/post, plan:pre/post, execute:pre/wave:pre/wave:post/post, verify:pre/post, ship:pre/post). The generator enforces a drift guard: every declared non-orchestrator agent role must correspond to an actual agent reference in the workflow file. Since #4740 it additionally enforces a **role-family partition** (ADR-894 §3, Amendment 2026-09-14): every role belongs to exactly one of three disjoint families — orchestration (`orchestrator`), planning (`researcher`/`planner`/`checker`), execution (`executor`/`verifier`) — and each step admits exactly one family, so `execute:*` never admits `orchestrator` and the orchestration steps (`discuss`, `verify`, `ship`) never admit `executor`/`verifier`. A step MAY declare a strict subset of its family; it may never declare outside it, and an unknown step fails CLOSED (unlike the points coverage check, which defers an unknown step to its canonical-set and duplicate nets — roles have no second net). This governs what a WORKFLOW may DECLARE, and is distinct from §3's separate rule that a capability's `contribution.into` must be a member of the step's `agentRoles`, which governs what a CAPABILITY may TARGET and is unchanged. Consumed by `gen-capability-registry.cjs` (replaces the former inline `LOOP_HOST_CONTRACT` constant). Run `node scripts/gen-loop-host-contract.cjs --write` after editing a workflow step marker.
 
 ### Gate Predicate Evaluator Module
 Pure, deps-injected evaluator for capability gate `check.predicate` blocks (#2008, ADR-2008). Prior to #2008 the registry validator accepted `check.predicate` (one of exactly-one-of `query`/`predicate`/`agentVerdict`) and the loop-resolver rendered it, but nothing EVALUATED a declared predicate — only `check.query` was enforced (dispatched via `gsd_run check <query>`), and built-in gates like `security` worked only via hard-coded `capId` prose branches in `ship.md`/`execute-phase.md`/`verify-work.md`. This module is the generic evaluation path: `evaluatePredicate(predicate, context, deps) → { block, message, details? }` dispatches by `predicate.kind` through a `KIND_TABLE`. Built-in kinds: `command-exit-zero` runs a declared command in a bounded `sh -c` subprocess (production binding: `shell-command-projection.execTool`) at the project root, inheriting env; exit 0 ⇒ pass, non-zero ⇒ block, timeout (SIGTERM) ⇒ block; `artifact-frontmatter-equals` resolves a phase or project-level Markdown artifact through injected dependencies and compares a frontmatter field by scalar string value. Command predicates interpolate `${PHASE_NUMBER}`/`${PHASE_DIR}`/`${PHASE_REQ_IDS}` from gate context. A THROWN error (malformed predicate, non-positive/non-finite timeout, command >4096 chars, missing dependencies, unknown kind) maps at the CLI seam to a non-zero check-command exit, which the workflow's two-step gate contract treats as a step-1 command failure routed per `onError` — so an evaluator bug is never conflated with a legitimate block decision. Leaf pure module (no fs/child_process/config — subprocess and artifact seams injected). CLI entry: `gsd_run check predicate --predicate '<json>' [--phase-dir …] [--phase-number …] [--phase-req-ids …] --raw`, wired into `check-command-router.cts:cmdCheckPredicate`. `--phase-dir` is CONFINED to the project root at that router boundary (#4354, epic #4636 Phase 2): an unconfined value let a BLOCKING gate return `block: false` on an artifact in a directory the caller chose, and the same value interpolates into `${PHASE_DIR}` for `command-exit-zero`, so confining at the boundary covers BOTH kinds while keeping this module's fs-free leaf contract intact — a fix inside the evaluator would have required giving a pure module a filesystem dependency and would still have missed the interpolation path. The four generic workflow gate-dispatch sites (`execute:wave:post`, `execute:post`, `plan:post`, and `ship:pre` — the last wired by #3559, which had resolved gates generically but enforced only two hardcoded `capId`s) branch on `check` shape (`query` vs `predicate`). Source of truth: `src/gate-predicate-evaluator.cts`. Docs: `docs/reference/gate-predicates.md`, `docs/how-to/command-exit-zero-gate.md`.
@@ -404,7 +404,7 @@ ADR-1244 Phase 4 (D5+D6) orchestration seam (`gsd-core/bin/lib/capability-lifecy
 ADR-1244 Phase 5 (D7) registry-driven dispatch of capability command families. First-party families (`graphify`/`intel`/`audit`, shipped in `bin/lib/`) dispatch via `dispatchCapabilityCommand` (`gsd-core/bin/gsd-tools.cjs`) against the FROZEN `capability-registry.cjs` `commandFamilies` (confined to `bin/lib/`) — unchanged. Third-party (installed overlay) families dispatch via `dispatchOverlayCapabilityCommand`: after the first-party path returns false, it calls `loadRegistry({ includeInstalled, cwd })` and dispatches a family iff its `capId` is in `_overlay.commandRoots` — which `capability-loader.cjs` populates ONLY for accepted overlay capabilities that declare `commands` AND pass the loader's activation gate (a **committed** ledger entry, present and non-`_pending`, PLUS — for PROJECT scope — a matching user consent record in the Capability Consent Store; GLOBAL scope needs no consent record). A bundle dropped on disk with no install (no ledger entry) or no on-this-machine consent is NOT command-dispatchable. The router module is `require()`'d FROM the capability's install root via `defaultRequireFromInstallRoot` (bare-`.cjs` basename + `realpath` containment, rejecting `..` traversal and symlink escape); same own-property/function/sync-only guards as the first-party path. Wired into the `runCommand` default arm before "Unknown command". A repo-planted project ledger no longer activates anything on its own (#1459) — see `docs/explanation/capability-trust-model.md` "project-scope trust boundary".
 
 ### Claude Orchestration Capability
-Default-off, BETA, claude-only Capability (`capabilities/claude-orchestration/`, `role: feature`, `runtimeCompat.supported: ["claude"]`, `tier: full`, `activationKey: claude_orchestration.enabled`) adopting Claude Code's Workflow tool (the engine behind `/effort ultracode`, Agent SDK ≥ v0.3.149) as an optional parallel-execution backend for the GSD loop, and folding the `gsd-ultraplan-phase` plan-offload under the same runtime gate (#1143; ADR-1143). Pure, fail-closed core in `gsd-core/bin/lib/claude-orchestration.cjs`: `detectWorkflowBackend({ runtimeId, hostIntegration, config, agentSdkVersion }) → { available, backend:'workflow'|'inline', reason }` (gate ladder: enabled → Claude → execution_backend ≠ inline → host dispatch nested+background → valid Agent SDK → SDK ≥ floor; every miss degrades to `inline`, never throws); `emitWorkflowScript({ phaseDir, waves, runId, budgetTokens?, executorModel? }) → { ok, script, summary }` mapping waves → `parallel()` stage barriers, plans → `agent({ agentType:'gsd-executor', isolation:'worktree', model? })`, `files_modified` overlap → separate sequential stages (greedy first-fit), `resumeFromRunId` wired to the run id, shared `budget(tokens)`; all interpolated identifiers validated script-safe (no `"`,`\`,control chars) and briefs JSON-quoted (review anti-injection). #2686: `executorModel` — resolved for `gsd-executor` from the same config the inline path reads, defaulted by the router so no caller change is needed, `--executor-model` to pin — is emitted per plan and OMITTED when it resolves to `inherit`/empty/whitespace/non-string (#2517: an empty model 404s on runtimes without native tier aliases); a value carrying an unscriptable character is rejected outright (`ok:false`) rather than quoted, because the ADR-1411 provenance header interpolates it into a `//` comment where U+2028/U+2029 would terminate the comment and execute the remainder. `resolveWaveDispatch` forwards it. Registers two loop contributions at WIRED points only (execute:wave:pre/execute:pre are declared but not rendered, same constraint external-job documents): `execute:wave:post into:executor` (Workflow-backend guidance) and `plan:post into:planner` (ultraplan ownership declaration), both `when: claude_orchestration.enabled`, `onError: skip`. Federated config keys (`claude_orchestration.enabled` default false, `execution_backend` enum auto|workflow|inline default auto, `min_agent_sdk_version` string default "0.3.149") live only in the registry — uninstall removes them cleanly. Pre-release versions of the floor compare below GA (SemVer precedence). Restores the wave parallelism + plan-checker + verifier that #853 forces inline on Claude Code; on any runtime lacking the Workflow tool, behaviour is byte-identical to today. BETA v1 ships detection + emission + declarative ultraplan ownership + a `claude-orchestration` command family (`gsd-tools claude-orchestration detect-backend|emit-workflow`, router `gsd-core/bin/lib/claude-orchestration-command-router.cjs` from `src/claude-orchestration-command-router.cts`); full install-profile migration of the ultraplan skill into `skills[]` is a follow-up (CLUSTERS/profile gate). Test anchors: `tests/claude-orchestration.test.cjs`, `tests/claude-orchestration-command-router.test.cjs`.
+Default-off, BETA, claude-only Capability (`capabilities/claude-orchestration/`, `role: feature`, `runtimeCompat.supported: ["claude"]`, `tier: full`, `activationKey: claude_orchestration.enabled`) adopting Claude Code's Workflow tool (the engine behind `/effort ultracode`, Agent SDK ≥ v0.3.149) as an optional parallel-execution backend for the GSD loop, and folding the `gsd-ultraplan-phase` plan-offload under the same runtime gate (#1143; ADR-1143). Pure, fail-closed core in `gsd-core/bin/lib/claude-orchestration.cjs`: `detectWorkflowBackend({ runtimeId, hostIntegration, config, agentSdkVersion }) → { available, backend:'workflow'|'inline', reason }` (gate ladder: enabled → Claude → execution_backend ≠ inline → host dispatch nested+background → valid Agent SDK → SDK ≥ floor; every miss degrades to `inline`, never throws); `emitWorkflowScript({ phaseDir, waves, runId, budgetTokens?, executorModel? }) → { ok, script, summary }` mapping waves → `parallel()` stage barriers, plans → `agent({ agentType:'gsd-executor', isolation:'worktree', model? })`, `files_modified` overlap → separate sequential stages (greedy first-fit), `resumeFromRunId` wired to the run id, shared `budget(tokens)`; all interpolated identifiers validated script-safe (no `"`,`\`,control chars) and briefs JSON-quoted (review anti-injection). #2686: `executorModel` — resolved for `gsd-executor` from the same config the inline path reads, defaulted by the router so no caller change is needed, `--executor-model` to pin — is emitted per plan and OMITTED when it resolves to `inherit`/empty/whitespace/non-string (#2517: an empty model 404s on runtimes without native tier aliases); a value carrying an unscriptable character is rejected outright (`ok:false`) rather than quoted, because the ADR-1411 provenance header interpolates it into a `//` comment where U+2028/U+2029 would terminate the comment and execute the remainder. `resolveWaveDispatch` forwards it. Registers one loop contribution at a WIRED point: `plan:post into:planner` (ultraplan ownership declaration), `when: claude_orchestration.enabled`, `onError: skip`. #4740 removed the earlier `execute:wave:pre into:executor` contribution outright (not retargeted) — its body was pure orchestrator procedure (build a wave manifest, resolve the dispatch backend, spawn executor agents) with nothing an executor agent could act on, so injecting it into executor prompts violated the loop's role partition; orchestration is not delivered through an agent contribution. The procedure text is preserved, unwired, at `capabilities/claude-orchestration/docs/workflow-backend-dispatch.md` as reference for a future host-level mechanism. Federated config keys (`claude_orchestration.enabled` default false, `execution_backend` enum auto|workflow|inline default auto, `min_agent_sdk_version` string default "0.3.149") live only in the registry — uninstall removes them cleanly. Pre-release versions of the floor compare below GA (SemVer precedence). Restores the wave parallelism + plan-checker + verifier that #853 forces inline on Claude Code; on any runtime lacking the Workflow tool, behaviour is byte-identical to today. BETA v1 ships detection + emission + declarative ultraplan ownership + a `claude-orchestration` command family (`gsd-tools claude-orchestration detect-backend|emit-workflow`, router `gsd-core/bin/lib/claude-orchestration-command-router.cjs` from `src/claude-orchestration-command-router.cts`); full install-profile migration of the ultraplan skill into `skills[]` is a follow-up (CLUSTERS/profile gate). Test anchors: `tests/claude-orchestration.test.cjs`, `tests/claude-orchestration-command-router.test.cjs`.
 ### Loop Extension Point
 A named, stable site on a host loop step (per-step `pre`/`post` plus per-wave in Execute; 12 total) where Capabilities register hooks. Three hook kinds: `step` (runs as its own sequenced unit), `contribution` (injects into the core step's prompt/context), and `gate` (checks and optionally blocks via a declared `blocking` flag). Each hook declares the artifacts it produces and consumes; hook order is derived by topological sort of that produces/consumes graph (capability-id tiebreak), which also defines data flow — file-artifact based, surviving `/clear` and fresh executor contexts. Hooks are surfaced by runtime resolution with concrete projection: the workflow calls a query that resolves the active hooks and returns fully-rendered, ordered markdown for the executor. Failure is default-resilient — a non-gate hook that errors is skipped with a warning; a hook may opt into `onError: halt`. Part of the Capability system. ADR-857 phase 3c ships the registry-consuming query layer: `gsd-core/bin/lib/loop-resolver.cjs` exposes `resolveLoopHooks({ point, registry, config })` (pure, no I/O), `renderLoopHooks(resolved)` (pure markdown renderer), and `cmdLoopRenderHooks(cwd, point, raw, opts)` (I/O entry point); activated via `gsd-tools loop render-hooks <point>` which emits `{ point, activeHooks[], rendered }`. Activation is driven by `when` (dotted config key resolved against `loadConfig`), with inline literal `__proto__`/`constructor`/`prototype` prototype-pollution guard. The first phase-6 cutovers wiring workflows to this query have landed — ui-phase at `plan:pre` and ui-review at `verify:post` (in `plan-phase.md`/`autonomous.md`); further per-feature cutovers are ongoing.
 

capabilities/claude-orchestration/capability.json

@@ -55,19 +55,6 @@
   },
   "steps": [],
   "contributions": [
-    {
-      "point": "execute:wave:pre",
-      "into": "executor",
-      "fragment": {
-        "path": "fragments/execute-wave-pre.md"
-      },
-      "produces": [],
-      "consumes": [
-        "PLAN.md"
-      ],
-      "when": "claude_orchestration.enabled",
-      "onError": "skip"
-    },
     {
       "point": "plan:post",
       "into": "planner",

capabilities/claude-orchestration/docs/workflow-backend-dispatch.md

@@ -1,7 +1,20 @@
 # Claude orchestration — Workflow execution backend (BETA)
 
-> Injected at `execute:wave:pre` `into: executor` only when
-> `claude_orchestration.enabled` is true. Default-off; `onError: skip`.
+> This is the orchestrator-side procedure for the Workflow execution backend.
+> It is NOT a loop contribution and is not injected anywhere. It was
+> previously declared as an `execute:wave:pre` contribution with
+> `into: "executor"`, which routed orchestrator instructions into executor
+> prompts — a role-partition violation (the orchestrator only orchestrates,
+> the executor only executes). It is retained here as the reference for
+> whoever wires the orchestrator side through a host-level mechanism. See
+> issue #4740.
+
+> **Editor's note:** the body below is preserved byte-for-byte from when this
+> file WAS the `execute:wave:pre` contribution fragment, so its section
+> headings and prose ("this contribution", "injected", etc.) still speak in
+> those terms. That is intentional — it is not being rewritten to match its
+> new status — and it is retained purely as the orchestrator-side reference
+> described above.
 
 ## When this contribution is active
 

docs/adr/1143-claude-orchestration-capability.md

@@ -130,3 +130,48 @@ execution path (actual orchestration via the Workflow tool inside Claude Code) i
 not verifiable outside that runtime. The capability is structurally complete and
 tested at the contract level; flipping to Accepted follows maintainer sign-off on
 the E2E behaviour once exercised on Claude Code with the Workflow tool present.
+
+## Amendment (2026-09-14): the `execute:wave:*` contribution is removed — orchestration is not an agent contribution
+
+Issue [#4740](https://github.com/open-gsd/gsd-core/issues/4740).
+
+Decision §2 and the 2026-07-06 amendment above are **historical record and are not rewritten**;
+this section supersedes them on the single point of loop registration.
+
+`capabilities/claude-orchestration/capability.json` declared a contribution at `execute:wave:pre`
+with `into: "executor"`. `gsd-core/references/loop-hook-dispatch.md` defines a contribution as
+*"Inject `fragment.inline` verbatim into the context for the role named in `into`"*, so that
+fragment was injected into **executor** prompts whenever `claude_orchestration.enabled`.
+
+Its 267 lines are orchestration end to end: construct a wave manifest, resolve the dispatch
+backend, invoke the Workflow tool to spawn executors, bridge per-agent results into the merge
+chain. An executor can act on none of it.
+
+**Retargeting it to `into: "orchestrator"` would not have been a fix.** `ROLE_TO_AGENT` carries no
+`orchestrator` entry by design — the orchestrator IS the host, not an agent, and the host's
+procedure lives in `gsd-core/workflows/execute-phase.md`. A step's `agentRoles` enumerates agents a
+capability may inject context INTO. Adding `orchestrator` there would model the host as an
+injectable agent: the same category error pointed the other way, and it would have required
+carving an exception into the role partition ADR-894 §3's 2026-09-14 amendment had just made
+normative.
+
+The defect is therefore the **mechanism**, not the label. A `contribution` injects into an agent's
+context; *"replace step 3's inline dispatch loop"* (`execute-phase.md:588`) is a change to what the
+**host** does. The contribution channel was being used as a host-behaviour directive because it was
+the only channel available at an `execute:*` point.
+
+**What changed:** the `execute:wave:pre` contribution is removed. The `plan:post` /
+`into: "planner"` contribution is correct and is untouched. The orchestrator-side procedure is
+preserved verbatim at `capabilities/claude-orchestration/docs/workflow-backend-dispatch.md` — it is
+the only copy in the repo — and is no longer injected anywhere.
+
+**Consequence, stated plainly:** the Workflow execution backend now has **no loop wiring**. Its
+detection and emission code (`detectWorkflowBackend`, `emitWorkflowScript`) and its federated
+config remain, and its design is intact in the preserved document, but nothing dispatches it. Under
+the orchestration/execution separation this ADR itself asserts — *"only the orchestrator (the
+script's return) writes shared files; executors stay in their worktrees"* — it never had a
+legitimate channel. This makes that visible rather than changing it, and the "Why this is still
+Proposed" audit above already records that the end-to-end path has never been exercised.
+
+Wiring it properly needs a **host-level mechanism** for a capability to alter the orchestrator's
+own dispatch procedure. That does not exist today and is not proposed here.

docs/adr/894-capability-declaration-format.md

@@ -267,3 +267,81 @@ This ADR was stress-tested in two rounds before merge; the format changed materi
 - The declarative-predicate vocabulary for gates (`artifact-exists`, `config-equals`, …).
 - The exact `commandStyle`/`sandboxTier`/`hooksSurface` enums for `role: runtime` (phase 5, against the 15 runtimes).
 - Point/role-set deprecation policy once third-party capabilities exist (additive-only holds until then; a rename/removal needs a major bump + deprecation window — deferred with third-party loading per ADR-857).
+
+## Amendment (2026-09-14): the role assignment in §3 is normative, and the families are disjoint
+
+Issue [#4740](https://github.com/open-gsd/gsd-core/issues/4740).
+
+§3 presents the per-step role assignment parenthesised as *"(illustrative roles)"*. That word was
+accurate about the list's **purpose** — it illustrated the shape of a generated contract entry — and
+wrong about its **status**, because the assignment was load-bearing from the moment the generator
+consumed it. Read literally it makes the partition an example rather than a rule, which is the
+reading this amendment closes. **The assignment in §3 is normative.**
+
+### The partition
+
+Every role belongs to exactly one of three disjoint families:
+
+| family | roles |
+|---|---|
+| orchestration | `orchestrator` |
+| planning | `researcher`, `planner`, `checker` |
+| execution | `executor`, `verifier` |
+
+Every loop step admits exactly one family:
+
+| step | admits |
+|---|---|
+| `discuss` | orchestration |
+| `plan` | planning |
+| `execute` | execution |
+| `verify` | orchestration |
+| `ship` | orchestration |
+
+**No step may declare roles from more than one family.** `execute:*` never admits `orchestrator`;
+the orchestration steps never admit `executor` or `verifier`. A step MAY declare a strict subset of
+its family (`execute: [executor]` is legal); it may never declare outside it.
+
+Orchestration and execution are distinct functions of the loop. The orchestrator decides what runs
+and owns the shared-state writes; an executor does one plan's work inside its own worktree. A
+contribution aimed at one is, by construction, not usable by the other — so a step that admitted
+both would be publishing an interface no reader could resolve.
+
+### Why this is a clarification, not a new decision
+
+§3's own mechanism already made the partition true in fact. The contract is generated from the
+workflow markers *"so it cannot drift into a lie"*, and all five step workflows have always declared
+single-family role sets. What was absent was any statement that this is **required**, and any check
+that it **holds**. This amendment supplies the first; the enforcement below supplies the second.
+No shipped behavior changes.
+
+### Enforcement
+
+`scripts/gen-loop-host-contract.cjs` gains `crossCheckRoleFamilies(step, agentRoles, fileName)`,
+which fails contract generation on a cross-family declaration, a role outside the vocabulary, or an
+unknown step. `lint:generated-sync` already runs `gen-loop-host-contract.cjs --check` in CI, so a
+violation blocks a PR.
+
+It **fails closed on an unknown step**, deliberately diverging from `assertPointsCoverage`'s
+`if (!expected) continue; // unknown step — caught elsewhere`. For *points* that comment is true —
+the canonical-set and cross-step duplicate checks catch it. For *roles* there is no second net, so
+failing open would leave an unknown step as the single input that bypasses the gate.
+
+This is **additive to §3's existing validation rule** (*"every `contribution.into` ∈ that step's
+`agentRoles`"*), which is unchanged. The two govern different actors and do not interact:
+
+| rule | governs | enforced by |
+|---|---|---|
+| `contribution.into ∈ agentRoles` (§3, unchanged) | what a **capability** may target | `capability-validator.cjs` |
+| role family matches the step (this amendment) | what a **workflow** may declare | `gen-loop-host-contract.cjs` |
+
+### Scope and limits
+
+- **Declarations only.** No capability is affected: a contribution targeting a legitimately-declared
+  role is valid before and after this amendment.
+- **No workflow changes.** All five already declare single-family sets, so the gate is green on the
+  same commit that introduces it. It constrains future edits.
+- **It does not make the partition unfalsifiable.** Someone may still edit
+  `EXPECTED_FAMILY_BY_STEP`. The value is that the boundary moves from an unstated property of five
+  workflow files to a named, reviewed constant with a test that fails when it changes — the same
+  bar §3 set for points.

docs/explanation/claude-orchestration-capability.md

@@ -36,13 +36,18 @@ gate. It is blocked-on-nothing now that the ADR-857 capability system is release
 - **`role: feature`**, `runtimeCompat.supported: ["claude"]`, `tier: full`.
 - **`activationKey: claude_orchestration.enabled`** — default `false`. Nothing
   changes until you opt in.
-- Registers at two **wired** loop points: `execute:wave:pre` (into the executor)
-  and `plan:post` (into the planner). Both are `onError: skip` and gated by the
-  `enabled` key. The dispatch-backend selector fires at `execute:wave:pre` — the
-  seam that runs immediately BEFORE a wave's agents are dispatched — because a
-  selector fired *after* a wave already dispatched inline (the original
-  `execute:wave:post` placement, [#2285]) is structurally too late to change how
-  dispatch happens.
+- Registers at one **wired** loop point: `plan:post` (into the planner),
+  `onError: skip` and gated by the `enabled` key. The capability previously
+  also contributed at `execute:wave:pre` (`into: executor`), but that fragment
+  was pure orchestrator procedure — build a wave manifest, resolve the
+  dispatch backend, spawn executor agents — with nothing an executor agent can
+  act on. Injecting orchestrator instructions into executor prompts violates
+  the loop's role partition (the orchestrator orchestrates, the executor
+  executes), so the contribution was removed ([#4740]). The procedure text is
+  preserved at
+  [`capabilities/claude-orchestration/docs/workflow-backend-dispatch.md`](../../capabilities/claude-orchestration/docs/workflow-backend-dispatch.md)
+  as reference for wiring the orchestrator side through a host-level
+  mechanism; it is not injected anywhere.
 
 ## How it decides whether to activate
 
@@ -106,3 +111,4 @@ own runtime gate continues to no-op on non-Claude runtimes.
 [#1143]: https://github.com/open-gsd/gsd-core/issues/1143
 [#2772]: https://github.com/open-gsd/gsd-core/issues/2772
 [#2285]: https://github.com/open-gsd/gsd-core/issues/2285
+[#4740]: https://github.com/open-gsd/gsd-core/issues/4740

docs/reference/capability-manifest.md

@@ -308,7 +308,7 @@ The following invariants are enforced at **build time** by `scripts/gen-capabili
 - **`requires` exist and are acyclic.** Every `id` listed in `requires` must exist in the registry; the dependency graph must be acyclic.
 - **`requires` is tier-monotone.** A `core` capability may not require a `standard` or `full` capability. A `standard` capability may not require a `full` capability.
 - **`point` values are from the closed set.** Every `point` in `steps`, `contributions`, and `gates` must be one of the 12 identifiers above.
-- **`contribution.into` is a published agent role.** The `into` value must be an agent role declared by the host contract for that loop extension point.
+- **`contribution.into` is a published agent role.** The `into` value must be an agent role declared by the host contract for that loop extension point. The published roles are **family-partitioned** (ADR-894 §3, Amendment 2026-09-14): every role belongs to exactly one of orchestration (`orchestrator`), planning (`researcher`, `planner`, `checker`) or execution (`executor`, `verifier`), and each loop step publishes exactly one family. So `execute:*` publishes `executor`/`verifier` and never `orchestrator`, and `discuss:*`/`verify:*`/`ship:*` publish `orchestrator` and never `executor`/`verifier`. The partition is enforced when the host contract is generated, so the role set a point publishes is stable rather than incidental.
 - **Config key exclusivity.** A federated config key must be owned by exactly one capability and absent from the central `config-schema`. Presence in both is a collision; a half-migrated key fails the build gate.
 - **Artefact production uniqueness per point.** No two capability steps may `produces` the same artefact name at the same loop extension point.
 - **`engines.gsd` is a hard gate.** A capability whose `engines.gsd` range does not satisfy the installed GSD version is blocked at install and skipped (with a warning) at load time.

docs/reference/capability-matrix.md

@@ -56,7 +56,7 @@ points.
 | `assumption-delta` | feature | full | `>=1.6.0` | `plan:pre` | contribution | first-party |
 | `audit` | feature | full | `>=1.6.0` | — | — | first-party |
 | `broken-windows` | feature | full | `>=1.7.0` | `ship:pre` | gate | first-party |
-| `claude-orchestration` | feature | full | `>=1.7.0` | `plan:post`, `execute:wave:pre` | contribution | first-party |
+| `claude-orchestration` | feature | full | `>=1.7.0` | `plan:post` | contribution | first-party |
 | `code-review` | feature | full | `>=1.6.0` | `execute:wave:post`, `execute:post` | step | first-party |
 | `drift` | feature | full | `>=1.6.0` | `plan:pre`, `execute:wave:post` | gate | first-party |
 | `external-job` | feature | full | `>=1.7.0` | `plan:post`, `execute:wave:post` | contribution | first-party |

scripts/gen-loop-host-contract.cjs

@@ -78,6 +78,23 @@ const ROLE_TO_AGENT = {
   verifier:   'gsd-verifier',
 };
 
+// #4740 — Role → family mapping. Three families: orchestration, planning,
+// execution. This constrains what a workflow may DECLARE in agent-roles for
+// a given step (admissibility), a separate concern from ROLE_TO_AGENT's
+// agent-file presence check above.
+const ROLE_FAMILY = {
+  orchestrator: 'orchestration',
+  researcher: 'planning', planner: 'planning', checker: 'planning',
+  executor: 'execution', verifier: 'execution',
+};
+const EXPECTED_FAMILY_BY_STEP = {
+  discuss: 'orchestration',
+  plan: 'planning',
+  execute: 'execution',
+  verify: 'orchestration',
+  ship: 'orchestration',
+};
+
 // ─── Parser ───────────────────────────────────────────────────────────────────
 
 /**
@@ -228,6 +245,52 @@ function crossCheckRoles(content, agentRoles, fileName) {
   return errors;
 }
 
+// ─── Cross-check: declared roles vs. their permitted family (#4740) ──────────
+
+/**
+ * For a step, verify every role declared in agentRoles belongs to that step's
+ * expected family (orchestration / planning / execution).
+ *
+ * Unlike `assertPointsCoverage`'s `if (!expected) continue // caught
+ * elsewhere` guard, an unknown step here fails CLOSED: for points
+ * there is a second net (the canonical-set and duplicate checks), but nothing
+ * else in the repo validates role families, so failing open on an unknown
+ * step would make it the one input that silently bypasses this gate — the
+ * "unknown resolving to a safe known" failure mode this check exists to close.
+ *
+ * Pure: never sorts, de-dupes, or otherwise mutates `agentRoles` — the same
+ * array `buildContract` puts into the generated contract.
+ *
+ * @param {string}   step        The step named in the marker block.
+ * @param {string[]} agentRoles  Roles declared in the block.
+ * @param {string}   fileName    For error messages.
+ * @returns {string[]}           Array of error strings; empty = OK.
+ */
+function crossCheckRoleFamilies(step, agentRoles, fileName) {
+  const expectedFamily = EXPECTED_FAMILY_BY_STEP[step];
+  if (!expectedFamily) {
+    return [fileName + ': step "' + step + '" has no entry in EXPECTED_FAMILY_BY_STEP'];
+  }
+
+  const errors = [];
+  for (const role of agentRoles) {
+    const family = ROLE_FAMILY[role];
+    if (!family) {
+      errors.push(
+        fileName + ': declared agent-role "' + role + '" has no entry in ROLE_FAMILY mapping',
+      );
+      continue;
+    }
+    if (family !== expectedFamily) {
+      errors.push(
+        fileName + ': declared agent-role "' + role + '" (family "' + family +
+        '") is not permitted at step "' + step + '" (expected family "' + expectedFamily + '")',
+      );
+    }
+  }
+  return errors;
+}
+
 // ─── 12-points coverage assertion ────────────────────────────────────────────
 
 /**
@@ -331,6 +394,10 @@ function buildContract(workflowsDir) {
     const roleErrors = crossCheckRoles(content, entry.agentRoles, file);
     allErrors.push(...roleErrors);
 
+    // Cross-check role families (#4740)
+    const roleFamilyErrors = crossCheckRoleFamilies(entry.step, entry.agentRoles, file);
+    allErrors.push(...roleFamilyErrors);
+
     for (const auxiliary of auxiliaryHosts) {
       let auxiliaryContent;
       try {
@@ -667,6 +734,7 @@ function getWiredLoopPoints(repoRoot) {
 module.exports = {
   parseLoopHostBlock,
   crossCheckRoles,
+  crossCheckRoleFamilies,
   assertPointsCoverage,
   buildContract,
   serializeContract,
@@ -676,6 +744,7 @@ module.exports = {
   CANONICAL_POINTS,
   EXPECTED_POINTS_BY_STEP,
   ROLE_TO_AGENT,
+  ROLE_FAMILY,
   scanWiredPoints,
   getWiredLoopPoints,
   coveredKindsInRegion,

tests/claude-orchestration.test.cjs

@@ -806,7 +806,7 @@ describe('capability declaration (capabilities/claude-orchestration/capability.j
     assert.strictEqual(slice.default, 'auto');
   });
 
-  test('registers at WIRED points only (execute:wave:pre, plan:post)', () => {
+  test('registers at WIRED points only (plan:post) — #4740 removed execute:wave:pre', () => {
     const cap = loadCap();
     const points = cap.contributions.map((c) => c.point);
     for (const p of points) {
@@ -815,10 +815,10 @@ describe('capability declaration (capabilities/claude-orchestration/capability.j
         'contribution point ' + p + ' must be a wired point',
       );
     }
-    // #2285: the dispatch-backend selector moved from execute:wave:post (fires
-    // AFTER the wave already dispatched inline — too late to select a backend)
-    // to execute:wave:pre (fires BEFORE step 3's Agent() dispatch).
-    assert.ok(points.includes('execute:wave:pre'), 'registers the pre-wave dispatch-selector hook');
+    // #4740: the execute:wave:pre / into:executor contribution was pure
+    // orchestrator procedure with nothing an executor agent could act on —
+    // it was removed, not retargeted. Only plan:post (into:planner) remains.
+    assert.ok(!points.includes('execute:wave:pre'), 'no longer registers at execute:wave:pre (#4740)');
     assert.ok(points.includes('plan:post'), 'declares plan:* ownership for ultraplan (criterion 5)');
   });
 
@@ -852,16 +852,15 @@ describe('registry integration', () => {
     assert.strictEqual(registry.configSchema['claude_orchestration.execution_backend'].default, 'auto');
   });
 
-  test('byLoopPoint[execute:wave:pre].contributions includes our capability (#2285)', () => {
+  test('byLoopPoint[execute:wave:pre] no longer carries our contribution (#4740 removed it)', () => {
     const { capMap } = loadAndValidate(new Set());
     const registry = buildRegistry(capMap);
     const contribs = registry.byLoopPoint['execute:wave:pre'].contributions;
     const ours = contribs.find((c) => c.capId === 'claude-orchestration');
-    assert.ok(ours, 'our execute:wave:pre contribution is registered');
-    assert.strictEqual(ours.into, 'executor');
+    assert.strictEqual(ours, undefined, 'claude-orchestration must not remain at execute:wave:pre (#4740)');
   });
 
-  test('byLoopPoint[execute:wave:post] no longer carries our contribution (#2285 moved it to wave:pre)', () => {
+  test('byLoopPoint[execute:wave:post] does not carry our contribution', () => {
     const { capMap } = loadAndValidate(new Set());
     const registry = buildRegistry(capMap);
     const contribs = registry.byLoopPoint['execute:wave:post'].contributions;
@@ -1515,28 +1514,30 @@ describe('C. resolveWaveDispatch composes detectWorkflowBackend + emitWorkflowSc
   });
 });
 
-// ─── Section D: capability declaration now targets execute:wave:pre ─────────
+// ─── Section D: capability declaration no longer contributes at execute:wave:pre (#4740) ──
 
-describe('D. capability.json declares the contribution at execute:wave:pre (#2285)', () => {
-  test('[happy] contribution point is execute:wave:pre, not execute:wave:post', () => {
+describe('D. capability.json no longer declares a contribution at execute:wave:pre (#4740)', () => {
+  test('[happy] neither execute:wave:pre nor execute:wave:post carries a contribution', () => {
+    // #4740: the execute:wave:pre / into:executor contribution was pure
+    // orchestrator procedure (build a wave manifest, resolve the dispatch
+    // backend, spawn executor agents) with nothing an executor agent can
+    // act on — injecting it into executor prompts violated the loop's role
+    // partition. It was removed outright, not retargeted.
     const cap = JSON.parse(fs.readFileSync(CAP_PATH, 'utf8'));
     const wavePreContrib = cap.contributions.find((c) => c.point === 'execute:wave:pre');
-    assert.ok(wavePreContrib, 'capability.json must declare a contribution at execute:wave:pre');
-    assert.strictEqual(wavePreContrib.into, 'executor');
-    assert.strictEqual(wavePreContrib.when, 'claude_orchestration.enabled');
-    assert.strictEqual(wavePreContrib.onError, 'skip');
-    assert.strictEqual(wavePreContrib.fragment.path, 'fragments/execute-wave-pre.md');
+    assert.strictEqual(wavePreContrib, undefined, 'capability.json must no longer declare a contribution at execute:wave:pre');
 
     const wavePostContrib = cap.contributions.find((c) => c.point === 'execute:wave:post');
-    assert.strictEqual(wavePostContrib, undefined, 'the capability must no longer contribute at execute:wave:post');
+    assert.strictEqual(wavePostContrib, undefined, 'the capability must not contribute at execute:wave:post either');
   });
 
-  test('[happy] the declared fragment file exists on disk', () => {
-    const fragPath = path.join(ROOT, 'capabilities', 'claude-orchestration', 'fragments', 'execute-wave-pre.md');
-    assert.ok(fs.existsSync(fragPath), 'fragments/execute-wave-pre.md must exist');
-    const content = fs.readFileSync(fragPath, 'utf8');
+  test('[happy] the preserved procedure doc exists on disk (moved, not deleted)', () => {
+    const docPath = path.join(ROOT, 'capabilities', 'claude-orchestration', 'docs', 'workflow-backend-dispatch.md');
+    assert.ok(fs.existsSync(docPath), 'capabilities/claude-orchestration/docs/workflow-backend-dispatch.md must exist');
+    const content = fs.readFileSync(docPath, 'utf8');
     assert.match(content, /execute:wave:pre/);
     assert.match(content, /resolve-wave-dispatch/);
+    assert.match(content, /#4740/, 'header must reference the issue that removed the contribution');
   });
 });
 
@@ -1759,9 +1760,11 @@ describe('G. missing top-level `waves` key never silently exits 0 with no output
 
 // ─── Section H: orthogonal-review finding 3 — manifest construction guidance is concrete ──
 
-describe('H. the execute:wave:pre fragment documents concrete manifest construction (finding 3)', () => {
-  test('[happy] the fragment explains how to build WAVE_MANIFEST_PATH, PHASE_RUN_ID, and per-plan use_worktree', () => {
-    const fragPath = path.join(ROOT, 'capabilities', 'claude-orchestration', 'fragments', 'execute-wave-pre.md');
+describe('H. the workflow-backend-dispatch doc documents concrete manifest construction (finding 3)', () => {
+  test('[happy] the doc explains how to build WAVE_MANIFEST_PATH, PHASE_RUN_ID, and per-plan use_worktree', () => {
+    // #4740: moved out of capabilities/claude-orchestration/fragments (no
+    // longer a loop contribution) to capabilities/claude-orchestration/docs.
+    const fragPath = path.join(ROOT, 'capabilities', 'claude-orchestration', 'docs', 'workflow-backend-dispatch.md');
     const content = fs.readFileSync(fragPath, 'utf8');
     assert.match(content, /Manifest construction/, 'fragment must have concrete manifest-construction guidance, not just reference undefined vars');
     assert.match(content, /PHASE_RUN_ID/);
@@ -1797,17 +1800,22 @@ describe('H. the execute:wave:pre fragment documents concrete manifest construct
   });
 });
 
-// ─── Section I: orthogonal-review finding 4 — stale doc fixed ───────────────
+// ─── Section I: docs/explanation/claude-orchestration-capability.md reflects the #4740 removal ──
 
-describe('I. docs/explanation/claude-orchestration-capability.md reflects the execute:wave:pre move (finding 4)', () => {
-  test('[happy] the doc no longer claims the capability registers at execute:wave:post', () => {
+describe('I. docs/explanation/claude-orchestration-capability.md reflects the #4740 removal', () => {
+  test('[happy] the doc no longer claims the capability registers at execute:wave:pre or execute:wave:post', () => {
     const docPath = path.join(ROOT, 'docs', 'explanation', 'claude-orchestration-capability.md');
     const content = fs.readFileSync(docPath, 'utf8');
-    assert.match(content, /execute:wave:pre/, 'doc must mention execute:wave:pre as the wired point');
+    assert.match(
+      content,
+      /Registers at one \*\*wired\*\* loop point: `plan:post`/,
+      'doc must state the capability registers at exactly one wired loop point (plan:post)',
+    );
     assert.ok(
       !/execute:wave:post.*\(into the executor\)/.test(content),
       'doc must not still claim the wired point is execute:wave:post',
     );
+    assert.match(content, /plan:post/, 'doc must still mention the surviving plan:post contribution');
   });
 });
 
@@ -2231,8 +2239,11 @@ describe('#3302: emitted Workflow script returns per-agent outcomes for the mani
   });
 });
 
-describe('#3302: the execute:wave:pre fragment bridges Workflow results into the manifest merge chain', () => {
-  const FRAG_3302 = path.join(ROOT, 'capabilities', 'claude-orchestration', 'fragments', 'execute-wave-pre.md');
+describe('#3302: the workflow-backend-dispatch doc bridges Workflow results into the manifest merge chain', () => {
+  // #4740: this content is no longer an injected loop contribution (it was
+  // orchestrator procedure wrongly targeted `into: executor`); it now lives
+  // as a plain reference doc, content preserved verbatim.
+  const FRAG_3302 = path.join(ROOT, 'capabilities', 'claude-orchestration', 'docs', 'workflow-backend-dispatch.md');
 
   function fragContent() {
     return fs.readFileSync(FRAG_3302, 'utf8');

tests/execute-wave-post-gate-pipeline-e2e.test.cjs

@@ -652,9 +652,9 @@ describe('F. Real registry execute:wave:post shape — guard against accidental
       `execute:wave:post step ref must be { agent: 'gsd-dom-verifier' }; got ${JSON.stringify(domUatStep.ref)}`);
     assert.strictEqual(domUatStep.onError, 'skip',
       `execute:wave:post step onError must be 'skip'; got ${domUatStep.onError}`);
-    // #2285: claude-orchestration's dispatch-backend-selector contribution moved
-    // from execute:wave:post to execute:wave:pre — wave:post fires AFTER the
-    // wave already dispatched inline, too late to select a dispatch backend.
+    // #4740: claude-orchestration never contributed here (external-job +
+    // mempalace are unrelated capabilities), so this assertion is unaffected
+    // by #4740 removing claude-orchestration's execute:wave:pre contribution.
     assert.strictEqual(point.contributions.length, 2,
       `execute:wave:post must have 2 contributions (external-job + mempalace); got ${point.contributions.length}`);
     const capIds = point.contributions.map(c => c.capId).sort();
@@ -662,15 +662,21 @@ describe('F. Real registry execute:wave:post shape — guard against accidental
       `execute:wave:post contributions must be external-job + mempalace; got ${capIds.join(',')}`);
   });
 
-  test('[happy] real registry: execute:wave:pre has 1 contribution (claude-orchestration dispatch-backend selector, #2285)', () => {
+  test('[happy] real registry: execute:wave:pre has 0 contributions (#4740 removed claude-orchestration\'s)', () => {
+    // #4740: the execute:wave:pre / into:executor contribution was pure
+    // orchestrator procedure (build a wave manifest, resolve the dispatch
+    // backend, spawn executor agents) with nothing an executor agent could
+    // act on — orchestration is not delivered through an agent contribution,
+    // so it was removed outright rather than retargeted. No capability
+    // contributes at execute:wave:pre anymore.
     const point = realRegistry.byLoopPoint['execute:wave:pre'];
     assert.strictEqual(point.steps.length, 0,
       `execute:wave:pre steps must be empty; got ${point.steps.length}`);
-    assert.strictEqual(point.contributions.length, 1,
-      `execute:wave:pre must have 1 contribution (claude-orchestration); got ${point.contributions.length}`);
+    assert.strictEqual(point.contributions.length, 0,
+      `execute:wave:pre must have 0 contributions (#4740); got ${point.contributions.length}`);
     const capIds = point.contributions.map(c => c.capId).sort();
-    assert.deepStrictEqual(capIds, ['claude-orchestration'],
-      `execute:wave:pre contributions must be claude-orchestration; got ${capIds.join(',')}`);
+    assert.deepStrictEqual(capIds, [],
+      `execute:wave:pre contributions must be empty; got ${capIds.join(',')}`);
   });
 
 });

tests/loop-host-contract.test.cjs

@@ -13,12 +13,14 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const fc = require('fast-check');
 
 const { cleanup } = require('./helpers.cjs');
 
 const {
   parseLoopHostBlock,
   crossCheckRoles,
+  crossCheckRoleFamilies,
   assertPointsCoverage,
   buildContract,
   serializeContract,
@@ -27,6 +29,7 @@ const {
   CANONICAL_POINTS,
   EXPECTED_POINTS_BY_STEP,
   ROLE_TO_AGENT,
+  ROLE_FAMILY,
 } = require('../scripts/gen-loop-host-contract.cjs');
 
 const { LOOP_HOST_CONTRACT } = require('../gsd-core/bin/lib/loop-host-contract.cjs');
@@ -202,6 +205,158 @@ describe('crossCheckRoles', () => {
   });
 });
 
+// ─── 2b. crossCheckRoleFamilies (#4740) ──────────────────────────────────────
+
+describe('crossCheckRoleFamilies (#4740)', () => {
+  test('accepts the execution family at execute', () => {
+    const errors = crossCheckRoleFamilies('execute', ['executor', 'verifier'], 'execute-phase.md');
+    assert.deepEqual(errors, []);
+  });
+
+  test('accepts orchestrator at discuss', () => {
+    const errors = crossCheckRoleFamilies('discuss', ['orchestrator'], 'discuss-phase.md');
+    assert.deepEqual(errors, []);
+  });
+
+  test('accepts the planning family at plan', () => {
+    const errors = crossCheckRoleFamilies('plan', ['researcher', 'planner', 'checker'], 'plan-phase.md');
+    assert.deepEqual(errors, []);
+  });
+
+  test('accepts orchestrator at verify and ship', () => {
+    assert.deepEqual(crossCheckRoleFamilies('verify', ['orchestrator'], 'verify-work.md'), []);
+    assert.deepEqual(crossCheckRoleFamilies('ship', ['orchestrator'], 'ship.md'), []);
+  });
+
+  test('a strict subset of the family is legal', () => {
+    const errors = crossCheckRoleFamilies('execute', ['executor'], 'execute-phase.md');
+    assert.deepEqual(errors, []);
+  });
+
+  test('rejects orchestrator added to execute', () => {
+    const errors = crossCheckRoleFamilies('execute', ['executor', 'verifier', 'orchestrator'], 'execute-phase.md');
+    assert.strictEqual(errors.length, 1, 'expected exactly 1 error');
+    assert.match(errors[0], /orchestrator/);
+    assert.match(errors[0], /execute/);
+  });
+
+  test('rejects an execution role at an orchestration step', () => {
+    const errors = crossCheckRoleFamilies('discuss', ['orchestrator', 'executor'], 'discuss-phase.md');
+    assert.strictEqual(errors.length, 1, 'expected exactly 1 error');
+    assert.match(errors[0], /executor/);
+  });
+
+  test('rejects an execution role at plan', () => {
+    const errors = crossCheckRoleFamilies('plan', ['planner', 'executor'], 'plan-phase.md');
+    assert.strictEqual(errors.length, 1, 'expected exactly 1 error');
+    assert.match(errors[0], /executor/);
+  });
+
+  test('rejects a planning role at execute', () => {
+    const errors = crossCheckRoleFamilies('execute', ['executor', 'planner'], 'execute-phase.md');
+    assert.strictEqual(errors.length, 1, 'expected exactly 1 error');
+    assert.match(errors[0], /planner/);
+  });
+
+  test('rejects a role with no family', () => {
+    const errors = crossCheckRoleFamilies('execute', ['executer'], 'execute-phase.md');
+    assert.ok(errors.length >= 1, 'expected at least 1 error');
+    assert.ok(errors.some((e) => e.includes('executer')));
+  });
+
+  test('fails closed on an unknown step', () => {
+    const errors = crossCheckRoleFamilies('audit', ['orchestrator'], 'audit.md');
+    assert.strictEqual(errors.length, 1, 'expected exactly 1 error for unknown step');
+    assert.match(errors[0], /audit/);
+  });
+
+  test('rejects a role whose capitalization does not match', () => {
+    const errors = crossCheckRoleFamilies('execute', ['Orchestrator'], 'execute-phase.md');
+    assert.ok(errors.length >= 1, 'capitalized role must not silently match');
+    assert.ok(errors.some((e) => e.includes('Orchestrator')));
+  });
+
+  test('a duplicated in-family role is not an error', () => {
+    const errors = crossCheckRoleFamilies('execute', ['executor', 'executor'], 'execute-phase.md');
+    assert.deepEqual(errors, []);
+  });
+
+  test('reports every offending role, not just the first', () => {
+    const errors = crossCheckRoleFamilies('execute', ['executor', 'orchestrator', 'planner'], 'execute-phase.md');
+    assert.strictEqual(errors.length, 2, 'expected one error per offending role');
+    const combined = errors.join('\n');
+    assert.ok(combined.includes('orchestrator'));
+    assert.ok(combined.includes('planner'));
+  });
+
+  test('is pure and does not mutate its arguments', () => {
+    // Deliberately NOT alphabetically sorted — an in-place agentRoles.sort()
+    // must be caught by THIS test, not merely coincide with already-sorted
+    // input (#4740 review finding).
+    const agentRoles = ['verifier', 'executor', 'orchestrator'];
+    const snapshot = agentRoles.slice();
+    const first = crossCheckRoleFamilies('execute', agentRoles, 'execute-phase.md');
+    assert.deepEqual(agentRoles, snapshot, 'input array must not be mutated');
+    const second = crossCheckRoleFamilies('execute', agentRoles, 'execute-phase.md');
+    assert.deepEqual(first, second, 'repeated calls must produce identical results');
+    assert.deepEqual(agentRoles, snapshot, 'input array must still not be mutated after second call');
+  });
+
+  test('ROLE_FAMILY and ROLE_TO_AGENT cover the exact same role-name domain (#4740)', () => {
+    // Generative-fix-divergence guard: ROLE_FAMILY and ROLE_TO_AGENT are parallel
+    // constants over the same role-name domain (every non-orchestrator role, plus
+    // orchestrator which is family-only). Exact set equality both directions —
+    // not a subset check — so adding a role to only one map is caught here.
+    const familyKeys = new Set(Object.keys(ROLE_FAMILY));
+    const expectedKeys = new Set([...Object.keys(ROLE_TO_AGENT), 'orchestrator']);
+    assert.deepEqual(
+      [...familyKeys].sort(),
+      [...expectedKeys].sort(),
+      'ROLE_FAMILY keys must equal ROLE_TO_AGENT keys plus "orchestrator", exactly',
+    );
+  });
+
+  test('property: in-family subsets pass, any foreign role fails', () => {
+    const ROLE_FAMILY_LOCAL = {
+      orchestrator: 'orchestration',
+      researcher: 'planning', planner: 'planning', checker: 'planning',
+      executor: 'execution', verifier: 'execution',
+    };
+    const familyRoles = {
+      orchestration: ['orchestrator'],
+      planning: ['researcher', 'planner', 'checker'],
+      execution: ['executor', 'verifier'],
+    };
+    const stepsByFamily = {
+      discuss: 'orchestration', plan: 'planning', execute: 'execution',
+      verify: 'orchestration', ship: 'orchestration',
+    };
+    const steps = Object.keys(stepsByFamily);
+
+    fc.assert(
+      fc.property(
+        fc.constantFrom(...steps),
+        fc.subarray(Object.keys(ROLE_FAMILY_LOCAL), { minLength: 1 }),
+        (step, roles) => {
+          const family = stepsByFamily[step];
+          const inFamilySubset = familyRoles[family];
+          const errors = crossCheckRoleFamilies(step, inFamilySubset, 'x.md');
+          assert.deepEqual(errors, []);
+
+          const hasForeign = roles.some((r) => ROLE_FAMILY_LOCAL[r] !== family);
+          const errors2 = crossCheckRoleFamilies(step, roles, 'x.md');
+          if (hasForeign) {
+            assert.ok(errors2.length >= 1);
+          } else {
+            assert.deepEqual(errors2, []);
+          }
+        },
+      ),
+      { seed: 4740, numRuns: 200 },
+    );
+  });
+});
+
 // ─── 3. assertPointsCoverage ─────────────────────────────────────────────────
 
 describe('assertPointsCoverage', () => {
@@ -333,6 +488,19 @@ describe('buildContract from real workflows', () => {
     assert.deepEqual(ship.coreArtifacts.produces, []);
     assert.deepEqual(ship.coreArtifacts.consumes, ['UAT.md']);
   });
+
+  test('the shipped workflows declare no cross-family role (#4740)', () => {
+    // Pins something real about THIS change, distinct from the per-step field
+    // assertions above: running crossCheckRoleFamilies directly against every
+    // entry of the REAL contract returns zero errors for every step, not merely
+    // that buildContract() didn't throw (which every other test in this describe
+    // block already exercises incidentally).
+    const contract = buildContract();
+    for (const entry of contract) {
+      const errors = crossCheckRoleFamilies(entry.step, entry.agentRoles, entry.step + '.md');
+      assert.deepEqual(errors, [], 'step "' + entry.step + '" must declare no cross-family role');
+    }
+  });
 });
 
 // ─── 5. cross-check rejects nonexistent agent-role ───────────────────────────