coilyco-flight-deck/ward

Fork 0

Define discoverability contract for the post-ward-ops broker surface #1269

New issue

Open

opened 2026-07-14 10:08:49 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-07-14 10:08:49 +00:00

Member

Parent

coilysiren/inbox#212

What to decide

Define the discoverability contract for the post-ward ops broker or API surface that replaces the current Forgejo CLI tree for agent workflows.

Kai direction from 2026-07-15: pressure-test whether the advisor-recommended capability-manifest detail is actually necessary before asking an engineer to implement it. As written, this is not safe headless work.

Acceptance criteria

The design names the intended replacement surface for agent workflow operations, or narrows the remaining options with a concrete recommendation.
The design pressure-tests the advisor recommendation for a detailed capability manifest and says which fields are required now versus later.
The contract covers how agents discover issue, PR, CI/status, logs, comment, and merge capabilities without guessing verb spellings.
The design states what belongs in Ward, what belongs in AOS-hosted specgen/tooling, and what belongs in a broker/API layer.
The design explicitly rejects carrying forward old ward ops forgejo compatibility aliases unless they are temporary migration shims.
Follow-up implementation tickets are named for any work that should land after the contract is accepted.

Blocked by

Human/design pressure test. Kai doubts an engineer can headlessly implement this as written.

ward#1270 needs the result for PR/CI status and wait primitives.
coilyco-flight-deck/ward#1249 captures older speculative external-boundary thinking, but this issue is the updated direction from inbox#212.

Decision for release inclusion

Removed from warded control plane coherence on 2026-07-15. Keep as consult until the level of manifest/capability detail is accepted.

## Parent coilysiren/inbox#212 ## What to decide Define the discoverability contract for the post-`ward ops` broker or API surface that replaces the current Forgejo CLI tree for agent workflows. Kai direction from 2026-07-15: pressure-test whether the advisor-recommended capability-manifest detail is actually necessary before asking an engineer to implement it. As written, this is not safe headless work. ## Acceptance criteria - [ ] The design names the intended replacement surface for agent workflow operations, or narrows the remaining options with a concrete recommendation. - [ ] The design pressure-tests the advisor recommendation for a detailed capability manifest and says which fields are required now versus later. - [ ] The contract covers how agents discover issue, PR, CI/status, logs, comment, and merge capabilities without guessing verb spellings. - [ ] The design states what belongs in Ward, what belongs in AOS-hosted specgen/tooling, and what belongs in a broker/API layer. - [ ] The design explicitly rejects carrying forward old `ward ops forgejo` compatibility aliases unless they are temporary migration shims. - [ ] Follow-up implementation tickets are named for any work that should land after the contract is accepted. ## Blocked by Human/design pressure test. Kai doubts an engineer can headlessly implement this as written. ## Related - ward#1270 needs the result for PR/CI status and wait primitives. - coilyco-flight-deck/ward#1249 captures older speculative external-boundary thinking, but this issue is the updated direction from inbox#212. --- ## Decision for release inclusion Removed from `warded control plane coherence` on 2026-07-15. Keep as consult until the level of manifest/capability detail is accepted.

coilyco-ops added the

consult

labels

2026-07-14 10:08:49 +00:00

~~coilyco-ops referenced this issue 2026-07-14 10:09:01 +00:00~~

Implement agent-shaped PR/CI status and wait primitives #1270

coilyco-ops commented

2026-07-14 10:12:54 +00:00

Author

Member

🔎 ward agent advisor

ward agent advisor --harness codex ran a one-shot standard research pass on this question:

Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue.

Recommendation

Define the replacement as a Ward Workflow Broker capability contract, owned by ward, with a machine-readable capability manifest and a small execute path keyed by stable capability IDs. Do not make agents discover workflow operations by reading ward ops forgejo --help, generated KDL docs, or old command names.

Current repo state supports that direction:

ward ops forgejo is still a generated ward-kdl edge/operator surface. Docs call it an edge surface, and docs/config-source.md says core agent control-plane paths must not depend on it.
Core workflow code already has typed Go seams for issue threads and PR/CI workflows: Tracker, PRWorkflowClient, and the native ward agent pr verbs.
The read-only director already forwards launch, list, logs, stop, PR status, PR merge, CI runs, and CI rerun through the host dispatch broker.
There are two broker concepts today: the root credential broker for limited legacy ward ops forgejo write-tier issue leaves, and the host dispatch broker for director workflow actions. The replacement contract should name the host workflow broker as the agent workflow surface, not the legacy ops broker.

Recommended contract

Add a workflow capability registry exposed through ward agent capabilities --format json and through the broker itself as a capabilities action. The registry should be the thing agents read before acting.

Each capability entry should include:

id - stable semantic name, for example issue.read, issue.thread.read, issue.create, issue.comment, issue.close, issue.reopen, pr.read, pr.status, pr.merge, ci.runs.list, ci.run.rerun, run.dispatch, run.list, run.logs.read, run.stop.
provider - forgejo, github, shortcut, or a list where the seam is provider-neutral.
transport - local ward process, host dispatch broker, root credential broker, or unavailable.
scope - allowed owners, repo selectors, and whether bare #N resolution is supported.
mutability - read, write, destructive, or merge-gated.
role_gate - the embedded role and workflow permission rule that controls it.
input_schema and result_schema - enough JSON schema to call it without command-shape guessing.
streaming - whether output is streaming, especially for logs.
availability - available, degraded, unsupported, or provider gap. Example: CI rerun can report the current Forgejo API gap loudly.
docs - stable doc pointer.
since, deprecated, and optional replacement_for fields for migration.

The execute path should accept requests shaped around the capability ID, not a command argv clone:

{"capability":"pr.status","target":{"owner":"coilyco-flight-deck","repo":"ward","number":123},"params":{},"requester":"director-box","request_id":"..."}

Responses should be structured JSON first, with human text as an optional rendering field. Logs can keep a streaming mode, but the header should still be structured.

Layer split

ward owns workflow semantics: issue-thread contract, reservation comments, PR workflow gates, role permissions, merge policy, logs/list/stop/dispatch, capability registry, and human wrappers under ward agent.
The broker/API layer owns authenticated host-side execution and structured request/response transport. It should execute Ward workflow capabilities and re-check role gates host-side.
AOS-hosted specgen/tooling owns generated references and broad provider CRUD tooling. It can still render KDL/OpenAPI surfaces for operator use, but it should not be the source of truth for agent workflow operations.
ward-kdl remains useful for generic audited provider ops, not for the workflow control plane. It can provide temporary migration shims only.

Options considered

Carry forward ward ops forgejo as the agent surface: reject. It keeps old command spellings as product API, forces workflow semantics through provider CRUD names, and conflicts with the issue direction.
MCP as the primary surface: defer. MCP is good as a later projection of the same capability manifest, but making it primary adds hosting, client hydration, and auth lifecycle dependencies before the core contract exists.
HTTP or JSON-RPC as the primary surface: reasonable later if the broker must become remote or multi-host. For now the existing host dispatch broker can carry the contract with less surface area.
AOS-hosted KDL specgen as primary: reject for workflow ops. It is the wrong layer for runtime workflow policy. It remains appropriate for generated operator references and non-workflow provider surfaces.
Typed Go broker plus manifest: recommend. It matches current code, keeps Ward as the workflow engine, and gives agents a single discovery point.

Open questions

Whether ward agent capabilities should also support --capability <id> for one-entry lookup. Recommendation: yes, to keep prompts small.
Whether the root credential broker and host dispatch broker should share one public protocol name. Recommendation: document them separately now, then converge implementation later only if it reduces real duplication.
Whether issue capabilities should be fully provider-neutral on day one. Recommendation: expose provider availability per capability. Do not pretend PR/CI is provider-neutral while it is Forgejo-only.
Whether MCP projection is needed immediately. Recommendation: create a follow-up, but do not block the broker contract on it.
What deprecation window old CLI shims get. Recommendation: one explicit migration phase with warnings, no indefinite aliases.

Risks

Help-text discovery will regress into verb guessing.
Compatibility aliases can become a permanent second API unless they carry warnings, telemetry, and a removal issue.
Making MCP primary too early moves the hard part into deployment and client config instead of solving the contract.
Putting workflow config in AOS or KDL violates the repo’s own layer split: Ward owns runtime workflow policy.
Under-specifying mutability and role gates risks agents treating reads, comments, reruns, and merges as equivalent tool calls.
Conflating issue trackers with PR/CI forges will hide provider gaps until runtime.

Follow-up implementation tickets to file after the contract is accepted

ward: Add the workflow capability registry and ward agent capabilities --format json.
ward: Add a dispatch-broker capabilities action and a capability-ID execute request path.
ward: Move issue/comment workflow calls onto capability IDs, keeping provider availability explicit.
ward: Move PR/status/CI/log/list/stop/dispatch broker calls onto capability IDs while preserving existing ward agent pr, logs, list, and stop as human wrappers.
ward: Add migration warnings for any temporary ward ops forgejo workflow shims and document their removal condition.
agentic-os: Reframe the committed ward ops forgejo reference as legacy/generated operator reference, not the agent workflow discovery contract.

Bottom line: accept a typed Ward-owned capability manifest plus broker execute path as the replacement. Treat MCP and HTTP as projections of that contract, not as the contract itself. Keep old ward ops forgejo names out of new agent instructions except for short-lived migration shims.

Researched and posted automatically by ward agent advisor --harness codex (ward#179). This is one-shot research, not a carried change - verify before acting on it.

— Codex, via ward agent

### 🔎 ward agent advisor `ward agent advisor --harness codex` ran a one-shot **standard** research pass on this question: > Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue. --- **Recommendation** Define the replacement as a **Ward Workflow Broker capability contract**, owned by `ward`, with a machine-readable capability manifest and a small execute path keyed by stable capability IDs. Do not make agents discover workflow operations by reading `ward ops forgejo --help`, generated KDL docs, or old command names. Current repo state supports that direction: * `ward ops forgejo` is still a generated ward-kdl edge/operator surface. Docs call it an edge surface, and `docs/config-source.md` says core agent control-plane paths must not depend on it. * Core workflow code already has typed Go seams for issue threads and PR/CI workflows: `Tracker`, `PRWorkflowClient`, and the native `ward agent pr` verbs. * The read-only director already forwards launch, list, logs, stop, PR status, PR merge, CI runs, and CI rerun through the host dispatch broker. * There are two broker concepts today: the root credential broker for limited legacy `ward ops forgejo` write-tier issue leaves, and the host dispatch broker for director workflow actions. The replacement contract should name the host workflow broker as the agent workflow surface, not the legacy ops broker. **Recommended contract** Add a workflow capability registry exposed through `ward agent capabilities --format json` and through the broker itself as a `capabilities` action. The registry should be the thing agents read before acting. Each capability entry should include: * `id` - stable semantic name, for example `issue.read`, `issue.thread.read`, `issue.create`, `issue.comment`, `issue.close`, `issue.reopen`, `pr.read`, `pr.status`, `pr.merge`, `ci.runs.list`, `ci.run.rerun`, `run.dispatch`, `run.list`, `run.logs.read`, `run.stop`. * `provider` - `forgejo`, `github`, `shortcut`, or a list where the seam is provider-neutral. * `transport` - local ward process, host dispatch broker, root credential broker, or unavailable. * `scope` - allowed owners, repo selectors, and whether bare `#N` resolution is supported. * `mutability` - read, write, destructive, or merge-gated. * `role_gate` - the embedded role and workflow permission rule that controls it. * `input_schema` and `result_schema` - enough JSON schema to call it without command-shape guessing. * `streaming` - whether output is streaming, especially for logs. * `availability` - available, degraded, unsupported, or provider gap. Example: CI rerun can report the current Forgejo API gap loudly. * `docs` - stable doc pointer. * `since`, `deprecated`, and optional `replacement_for` fields for migration. The execute path should accept requests shaped around the capability ID, not a command argv clone: ```json {"capability":"pr.status","target":{"owner":"coilyco-flight-deck","repo":"ward","number":123},"params":{},"requester":"director-box","request_id":"..."} ``` Responses should be structured JSON first, with human text as an optional rendering field. Logs can keep a streaming mode, but the header should still be structured. **Layer split** * `ward` owns workflow semantics: issue-thread contract, reservation comments, PR workflow gates, role permissions, merge policy, logs/list/stop/dispatch, capability registry, and human wrappers under `ward agent`. * The broker/API layer owns authenticated host-side execution and structured request/response transport. It should execute Ward workflow capabilities and re-check role gates host-side. * AOS-hosted specgen/tooling owns generated references and broad provider CRUD tooling. It can still render KDL/OpenAPI surfaces for operator use, but it should not be the source of truth for agent workflow operations. * ward-kdl remains useful for generic audited provider ops, not for the workflow control plane. It can provide temporary migration shims only. **Options considered** * Carry forward `ward ops forgejo` as the agent surface: reject. It keeps old command spellings as product API, forces workflow semantics through provider CRUD names, and conflicts with the issue direction. * MCP as the primary surface: defer. MCP is good as a later projection of the same capability manifest, but making it primary adds hosting, client hydration, and auth lifecycle dependencies before the core contract exists. * HTTP or JSON-RPC as the primary surface: reasonable later if the broker must become remote or multi-host. For now the existing host dispatch broker can carry the contract with less surface area. * AOS-hosted KDL specgen as primary: reject for workflow ops. It is the wrong layer for runtime workflow policy. It remains appropriate for generated operator references and non-workflow provider surfaces. * Typed Go broker plus manifest: recommend. It matches current code, keeps Ward as the workflow engine, and gives agents a single discovery point. **Open questions** * Whether `ward agent capabilities` should also support `--capability <id>` for one-entry lookup. Recommendation: yes, to keep prompts small. * Whether the root credential broker and host dispatch broker should share one public protocol name. Recommendation: document them separately now, then converge implementation later only if it reduces real duplication. * Whether issue capabilities should be fully provider-neutral on day one. Recommendation: expose provider availability per capability. Do not pretend PR/CI is provider-neutral while it is Forgejo-only. * Whether MCP projection is needed immediately. Recommendation: create a follow-up, but do not block the broker contract on it. * What deprecation window old CLI shims get. Recommendation: one explicit migration phase with warnings, no indefinite aliases. **Risks** * Help-text discovery will regress into verb guessing. * Compatibility aliases can become a permanent second API unless they carry warnings, telemetry, and a removal issue. * Making MCP primary too early moves the hard part into deployment and client config instead of solving the contract. * Putting workflow config in AOS or KDL violates the repo’s own layer split: Ward owns runtime workflow policy. * Under-specifying mutability and role gates risks agents treating reads, comments, reruns, and merges as equivalent tool calls. * Conflating issue trackers with PR/CI forges will hide provider gaps until runtime. **Follow-up implementation tickets to file after the contract is accepted** * `ward`: Add the workflow capability registry and `ward agent capabilities --format json`. * `ward`: Add a dispatch-broker `capabilities` action and a capability-ID execute request path. * `ward`: Move issue/comment workflow calls onto capability IDs, keeping provider availability explicit. * `ward`: Move PR/status/CI/log/list/stop/dispatch broker calls onto capability IDs while preserving existing `ward agent pr`, `logs`, `list`, and `stop` as human wrappers. * `ward`: Add migration warnings for any temporary `ward ops forgejo` workflow shims and document their removal condition. * `agentic-os`: Reframe the committed `ward ops forgejo` reference as legacy/generated operator reference, not the agent workflow discovery contract. Bottom line: accept a typed Ward-owned capability manifest plus broker execute path as the replacement. Treat MCP and HTTP as projections of that contract, not as the contract itself. Keep old `ward ops forgejo` names out of new agent instructions except for short-lived migration shims. --- Researched and posted automatically by `ward agent advisor --harness codex` (ward#179). This is one-shot research, not a carried change - verify before acting on it.   — Codex, via `ward agent`