Reflow the workflow lane enum: drop remote-branch-only, rename the three PR lanes to name their gate holder #1679

New issue

Open

opened 2026-08-23 00:11:27 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-23 00:11:27 +00:00

Member

Requested by Kai on 2026-08-22. Filed here rather than in agentic-os-kai - see "Where this is actually defined" below, because the guess was wrong and it matters for sequencing.

The change

Ward's canonical enum today, per ward agent --help and recorded on coilyco-flight-deck/agentic-os#994:

merge-remote-main | pull-request | pull-request-and-merge | remote-branch-only

default merge-remote-main

Target enum:

merge-remote-main | agent-author-merge | agent-reviewer-merge | human-reviewer-merge

default merge-remote-main

Two changes at once:

remote-branch-only is removed as a concept. Kai's call. It is declared by zero repos across all 32 active ones.
pull-request and pull-request-and-merge become three lanes named <actor>-<role>-merge, so the slug says who holds the merge gate. Design, rationale, and the per-repo assignment are on agentic-os#1189.

Lane semantics, Kai's words:

agent-author-merge - agent author creates the PR, merges their own PR
agent-reviewer-merge - agent author creates the PR, defers the merge, a reviewer agent merges
human-reviewer-merge - agent author creates the PR, defers the merge, a human merges

Where this is actually defined

Kai's guess was agentic-os-kai. It is not there - aosk only declares workflow: merge-remote-main for itself and carries no definitions. Five real surfaces:

surface	location	owner
the enum	`ward agent`, default `merge-remote-main`	this repo
prose	`agentic-os/AGENTS.md` lines 69-96 and 153	agentic-os
composed skill	`agentic-os/.agents/composed/coding-core-git-workflow`	agentic-os
per-repo declaration	`AGENTS.md` frontmatter `ward.workflow:` × 32 repos	each repo
server state	Forgejo branch protection	infrastructure

Ward is the lowest layer that fully determines the vocabulary, so under the config-placement law this repo owns the enum and everything else follows. That is why this issue is here: nothing downstream can land until Ward accepts the new values.

Note .ward/ward.yaml was checked in agentic-os, deploy, and ward and carries no workflow key in any of them, contrary to agentic-os#994's description of it as the config surface. The live declaration site is AGENTS.md frontmatter.

The prose is contradictory four ways, so migrating it is not mechanical

Anyone rewriting the downstream prose should know it does not currently agree with itself about what pull-request-and-merge means:

agentic-os/AGENTS.md line 71 - "open a PR for the director lane... merge only after... a passed review summary"
agentic-os/AGENTS.md lines 86, 88, 95 - the author "merges that pull request itself once it is green"
ward/AGENTS.md line 110, infrastructure line 43, sirens-echo line 161 - "the merge stays director-gated"
deploy/AGENTS.md line 52 - "an agent... merges that pull request itself once it is green"

Three repos say director-gated, two say self-merge, and agentic-os says both. Line 88 explicitly warns against the reading line 71 states.

The "byte-identical" invariant is already broken. Ward, infrastructure, and sirens-echo each claim their Git-workflow block is "byte-identical across the five PR-lane repos... per agentic-os#994." It is not:

deploy carries different text entirely (self-merge, plus an expired August 19 override note)
sirens-echo appends "Ward honors it only after ward#1661"
agentic-os has no such block at all

So the claim is false in three of the five, and whatever was meant to enforce it is not running. Worth a separate issue if that invariant is supposed to hold.

Migration reality

Because remote-branch-only and pull-request both have zero declarations, the removal and the split are free. The only frontmatter that must change is the five repos on pull-request-and-merge, plus the eleven repos moving lanes for other reasons - fourteen edits total, enumerated on agentic-os#1189.

Blocking dependency, inherited

agent-reviewer-merge has no dispatch mechanism. Nothing today invokes a reviewer agent to collect and merge a pull request. Four repos are slated for that lane, two of which are the highest-volume repos in the estate. Declaring it before dispatch exists strands work at an open PR nobody collects.

The sequencing on agentic-os#1189 holds those four repos on their current lanes until dispatch exists. This enum change does not need to wait - Ward can accept a value that is not yet widely declared.

Acceptance

Ward's enum accepts merge-remote-main, agent-author-merge, agent-reviewer-merge, human-reviewer-merge. Default unchanged.
remote-branch-only is removed. Since nothing declares it, no alias is needed - but confirm that against live ward.workflow values rather than trusting this issue's survey.
pull-request and pull-request-and-merge are accepted as deprecated aliases during migration, warning as direct-to-main did, then removed. pull-request-and-merge maps to agent-author-merge; pull-request has no unambiguous target (it meant both human-merge and reviewer-merge in different paragraphs) and should warn loudly rather than guess.
ward agent --help reflects the new enum, since #994 used it as the authority.
Ward's own behaviour per lane is verified, not just the enum's shape - sirens-echo/AGENTS.md notes "Ward honors it only after ward#1661," so honouring may be incomplete today.

agentic-os#1189 - prose rewrite, <actor>-<role>-merge naming, per-repo assignment for all 32 repos, and the reviewer-dispatch dependency
agent-compose#321 - the reviewing seat's close and revert authority
agentic-os#994 - the original three-surface drift sweep, still open; parts of it are superseded here and its .ward/ward.yaml finding looks stale
ward#1661 - referenced by sirens-echo as gating whether Ward honours the declared lane

Requested by Kai on 2026-08-22. **Filed here rather than in `agentic-os-kai`** - see "Where this is actually defined" below, because the guess was wrong and it matters for sequencing. ## The change Ward's canonical enum today, per `ward agent --help` and recorded on `coilyco-flight-deck/agentic-os#994`: ``` merge-remote-main | pull-request | pull-request-and-merge | remote-branch-only ``` default `merge-remote-main` Target enum: ``` merge-remote-main | agent-author-merge | agent-reviewer-merge | human-reviewer-merge ``` default `merge-remote-main` Two changes at once: 1. **`remote-branch-only` is removed as a concept.** Kai's call. It is declared by **zero repos** across all 32 active ones. 2. **`pull-request` and `pull-request-and-merge` become three lanes** named `<actor>-<role>-merge`, so the slug says who holds the merge gate. Design, rationale, and the per-repo assignment are on `agentic-os#1189`. Lane semantics, Kai's words: * `agent-author-merge` - agent author creates the PR, merges their own PR * `agent-reviewer-merge` - agent author creates the PR, defers the merge, a reviewer agent merges * `human-reviewer-merge` - agent author creates the PR, defers the merge, a human merges ## Where this is actually defined Kai's guess was `agentic-os-kai`. **It is not there** - aosk only declares `workflow: merge-remote-main` for itself and carries no definitions. Five real surfaces: | surface | location | owner | |---|---|---| | **the enum** | `ward agent`, default `merge-remote-main` | **this repo** | | prose | `agentic-os/AGENTS.md` lines 69-96 and 153 | agentic-os | | composed skill | `agentic-os/.agents/composed/coding-core-git-workflow` | agentic-os | | per-repo declaration | `AGENTS.md` frontmatter `ward.workflow:` × 32 repos | each repo | | server state | Forgejo branch protection | infrastructure | **Ward is the lowest layer that fully determines the vocabulary**, so under the config-placement law this repo owns the enum and everything else follows. That is why this issue is here: nothing downstream can land until Ward accepts the new values. Note `.ward/ward.yaml` was checked in agentic-os, deploy, and ward and carries **no** workflow key in any of them, contrary to `agentic-os#994`'s description of it as the config surface. The live declaration site is AGENTS.md frontmatter. ## The prose is contradictory four ways, so migrating it is not mechanical Anyone rewriting the downstream prose should know it does not currently agree with itself about what `pull-request-and-merge` means: * `agentic-os/AGENTS.md` **line 71** - "open a PR for **the director lane**... merge only after... a passed review summary" * `agentic-os/AGENTS.md` **lines 86, 88, 95** - the author "**merges that pull request itself once it is green**" * `ward/AGENTS.md` line 110, `infrastructure` line 43, `sirens-echo` line 161 - "the merge stays **director-gated**" * `deploy/AGENTS.md` line 52 - "an agent... **merges that pull request itself** once it is green" Three repos say director-gated, two say self-merge, and agentic-os says both. Line 88 explicitly warns against the reading line 71 states. **The "byte-identical" invariant is already broken.** Ward, infrastructure, and sirens-echo each claim their Git-workflow block is "byte-identical across the five PR-lane repos... per agentic-os#994." It is not: * `deploy` carries different text entirely (self-merge, plus an expired August 19 override note) * `sirens-echo` appends "Ward honors it only after ward#1661" * `agentic-os` has **no such block at all** So the claim is false in three of the five, and whatever was meant to enforce it is not running. Worth a separate issue if that invariant is supposed to hold. ## Migration reality Because `remote-branch-only` and `pull-request` both have **zero declarations**, the removal and the split are free. The only frontmatter that must change is the five repos on `pull-request-and-merge`, plus the eleven repos moving lanes for other reasons - fourteen edits total, enumerated on `agentic-os#1189`. ## Blocking dependency, inherited `agent-reviewer-merge` has **no dispatch mechanism**. Nothing today invokes a reviewer agent to collect and merge a pull request. Four repos are slated for that lane, two of which are the highest-volume repos in the estate. Declaring it before dispatch exists strands work at an open PR nobody collects. The sequencing on `agentic-os#1189` holds those four repos on their current lanes until dispatch exists. **This enum change does not need to wait** - Ward can accept a value that is not yet widely declared. ## Acceptance 1. Ward's enum accepts `merge-remote-main`, `agent-author-merge`, `agent-reviewer-merge`, `human-reviewer-merge`. Default unchanged. 2. `remote-branch-only` is removed. Since nothing declares it, no alias is needed - but confirm that against live `ward.workflow` values rather than trusting this issue's survey. 3. `pull-request` and `pull-request-and-merge` are accepted as **deprecated aliases** during migration, warning as `direct-to-main` did, then removed. `pull-request-and-merge` maps to `agent-author-merge`; `pull-request` has no unambiguous target (it meant both human-merge and reviewer-merge in different paragraphs) and should warn loudly rather than guess. 4. `ward agent --help` reflects the new enum, since #994 used it as the authority. 5. Ward's own behaviour per lane is verified, not just the enum's shape - `sirens-echo/AGENTS.md` notes "Ward honors it only after ward#1661," so honouring may be incomplete today. ## Related * `agentic-os#1189` - prose rewrite, `<actor>-<role>-merge` naming, per-repo assignment for all 32 repos, and the reviewer-dispatch dependency * `agent-compose#321` - the reviewing seat's close and revert authority * `agentic-os#994` - the original three-surface drift sweep, still open; parts of it are superseded here and its `.ward/ward.yaml` finding looks stale * `ward#1661` - referenced by sirens-echo as gating whether Ward honours the declared lane

coilyco-ops added the

labels

2026-08-23 00:11:27 +00:00