Add supervisor executor adapter contract by SoundBlaster · Pull Request #482 · 0al-spec/SpecGraph

SoundBlaster · 2026-05-31T20:54:02Z

Summary

Added a machine-readable supervisor executor adapter policy.
Added a viewer/operator contract document for the executor gateway request/report boundary.
Updated proposal 0056 with an explicit contract-only realization slice.
Clarified the responsibility split between deterministic SpecGraph core and a possible future SpecAgent runtime extraction.
Linked proposal 0056 to runtime/validation/observation markers so the graph can stop treating it as an unrealized proposal.
Link related issue/task (if any): proposal 0056

Motivation

The graph was highlighting 0056 as the next runtime realization gap.
The BYOK/demo runner path needs a SpecGraph-side executor gateway contract before any SpecSpace UI, provider config, or real runner implementation.
The same boundary is the right place to prevent SpecGraph core from absorbing non-deterministic runtime/provider responsibilities prematurely.
This keeps the next step small: contract first, feature later, repository split only after real pressure appears.

Goals

Define the bounded executor request shape: workspace root, target ref, provider config ref, policy envelope, and capability envelope.
Define the normalized executor report shape: status, run id, logs ref, produced artifacts, policy decisions, and error class.
Preserve the secret boundary: no API keys, raw provider secrets, web sessions, billing details, or raw prompts in persisted artifacts.
Define 0056 as the current in-repo anti-corruption layer between SpecGraph and possible future SpecAgent runtime concerns.
Out of scope: SpecSpace login, BYOK form, Timeweb deploy, real container runner, alternate executor implementation, Agent Passport enforcement, ontology work, and creating a new SpecAgent repo.

Changes

Added tools/supervisor_executor_adapter_policy.json.
Added docs/supervisor_executor_adapter_gateway_contract.md.
Added proposal 0056 contract-slice wording and SpecAgent extraction criteria.
Updated tools/proposal_runtime_registry.json markers for proposal 0056.
Added regression coverage for the policy shape and proposal-runtime closure.

Validation

Tests added/updated for changed behavior
Local checks passed

Commands run:

python -m json.tool tools/supervisor_executor_adapter_policy.json >/dev/null
python -m json.tool tools/proposal_runtime_registry.json >/dev/null
python -m pytest tests/test_supervisor.py -q -k "supervisor_executor_adapter_policy or proposal_0056_executor_adapter_contract"
make proposal-tracking-gate
make backlog
make next-move
make test-supervisor
git diff --check

Results:

Focused tests: 2 passed.
Proposal tracking gate: passed.
Backlog entry count dropped from 5 to 4; 0056 disappeared from runtime backlog.
make next-move now points to 0057.
Full supervisor suite: 728 passed.
Diff whitespace check passed.

Risks / Notes

Backward compatibility impact: none; no existing executor behavior changes.
Migration/config changes required: none.
Known limitations: this PR defines the contract only; it does not implement a real executor runner, BYOK UI, provider auth, Agent Passport enforcement, or a new SpecAgent repository.

Checklist

PR title clearly describes the change
Scope is focused and minimal
Documentation updated (or N/A)
No secrets or sensitive data added

Copilot

Pull request overview

This PR adds a contract-only realization slice for proposal 0056 (Supervisor Executor Adapter Gateway). It introduces a machine-readable policy artifact and a human-readable contract document defining the bounded request/report shapes for future executor adapters, without implementing any runtime backend. The proposal runtime registry is updated so 0056 no longer shows up as a runtime backlog gap, shifting next-move to 0057.

Changes:

Add tools/supervisor_executor_adapter_policy.json and docs/supervisor_executor_adapter_gateway_contract.md defining the executor request/report contract, error vocabulary, BYOK boundary, and non-overridable invariants.
Update proposal 0056 with a "Contract-Only Realization Slice" section and refresh its proposal runtime registry markers so it is implemented/covered.
Add two regression tests: a policy-shape test and a proposal 0056 runtime-closure test.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tools/supervisor_executor_adapter_policy.json	New machine-readable executor adapter policy artifact.
docs/supervisor_executor_adapter_gateway_contract.md	New viewer/operator contract document describing the gateway boundary.
docs/proposals/0056_supervisor_executor_adapter_gateway.md	Adds the contract-only realization slice section.
tools/proposal_runtime_registry.json	Updates 0056 runtime/validation/observation markers to the new contract surfaces.
tests/test_supervisor.py	Adds policy-shape and 0056 runtime-closure regression tests.

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

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e958dff5bb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-31T20:58:01Z

+    "runtime_markers": [
+      {
+        "path": "tools/supervisor_executor_adapter_policy.json",
+        "pattern": "\"artifact_kind\": \"supervisor_executor_adapter_policy\""
+      },


Keep 0056 in backlog until runtime criteria are met

With these runtime markers satisfied by only the new policy JSON/docs, build_proposal_runtime_index() now reports proposal 0056 as implemented/covered/covered with next_gap: none, so make backlog/make next-move skips it. That contradicts the same proposal's acceptance criteria, which still say runtime realization is complete only after policy-driven backend selection, pre-launch unsupported-backend failure, normalized run results feeding gates, smoke fixtures, and viewer-facing adapter artifacts exist; in the current contract-only slice those remain unimplemented, so this registry entry hides real remaining runtime work.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-05-31T20:58:01Z

+This document is the first SpecGraph-side contract surface for proposal
+`0056_supervisor_executor_adapter_gateway`.
+
+The gateway is a launch-and-observe boundary for nested supervisor executors. It
+does not implement a BYOK demo, a SpecSpace UI, a container runner, or an
+alternate executor backend. It defines the request and report shapes that future
+runtime implementations must use when they connect external executors to
+SpecGraph.


Synchronize the new contract with DocC

This new contract is published technical guidance for future executor implementations, but the commit does not add a corresponding Sources/SpecGraph/Documentation.docc/ page or update tools/docc_sync_contract.json. AGENTS.md requires DocC to stay synchronized whenever docs/ changes affect published technical guidance, so the public DocC docs will omit this executor adapter contract while the repository docs present it as canonical.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-05-31T20:58:01Z

+    "required_fields": [
+      "request_id",
+      "workspace_root",
+      "target_ref",
+      "provider_config_ref",
+      "policy_envelope",
+      "capability_envelope"


Carry the selected backend in executor requests

When an operator selects any non-default or experimental executor, this request contract has no backend_id/executor selector field to carry that choice into the gateway. That leaves future implementations relying on out-of-band state despite the policy requiring explicit experimental backend selection and unsupported-backend rejection before launch, and it also makes reports harder to audit against the backend that was actually requested.

Useful? React with 👍 / 👎.

Add supervisor executor adapter contract

e958dff

Copilot AI review requested due to automatic review settings May 31, 2026 20:54

Copilot started reviewing on behalf of SoundBlaster May 31, 2026 20:54 View session

Copilot AI reviewed May 31, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed May 31, 2026

View reviewed changes

Clarify SpecAgent extraction boundary

d5adf38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add supervisor executor adapter contract#482

Add supervisor executor adapter contract#482
SoundBlaster wants to merge 2 commits into
mainfrom
codex/supervisor-executor-adapter-contract

SoundBlaster commented May 31, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

SoundBlaster commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

Goals

Changes

Validation

Risks / Notes

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SoundBlaster commented May 31, 2026 •

edited

Loading