* 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>
This commit is contained in:
Tom Boucher
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user