coilyco-flight-deck/ward

Fork 0

PR-workflow tools (merge/status/rerun) must be native ward broker capabilities gated by ward's permission system, not runtime KDL specgen #1067

New issue

Closed

opened 2026-07-10 18:03:22 +00:00 by coilyco-ops · 5 comments

coilyco-ops commented

2026-07-10 18:03:22 +00:00

Member

Principle

PR-workflow management (merge, CI status read, run status, rerun) is a foundational ward-scale capability, so it must be implemented as native ward code gated by ward's own permission system - and must not depend on any runtime KDL specgen. Specgen (ward ops forgejo ... rendered from the swagger + coilyco .ward/ guardfiles) is the meld/custom layer. A foundational ward capability reaching up into it is the config-inversion the config-placement law forbids, and it is exactly why the 2026-07-10 permissions rollback could silently strip a director's ability to complete work (see infrastructure#538 fallout: a director surface could see the merge-ready PR wave but could neither read per-PR CI status nor merge).

The role presets (capabilities / modes / posture) already live embedded in ward's tree - roles.kdl says so explicitly ("The role presets ... are ward-embedded product data and live in ward's tree, not in this overlay"). Merge authority belongs there, next to the director/engineer role definitions, not in the specgen overlay.

Do

Implement the director's PR-workflow tools as native ward capabilities, most likely in the dispatch broker alongside the existing ward agent director merge composite:

Merge (POST /repos/{owner}/{repo}/pulls/{index}/merge) + merged-state check - performed through ward's own compiled Forgejo client, not by shelling to ward ops forgejo pr merge.
Combined CI status read (GET /repos/{owner}/{repo}/commits/{ref}/status) - so the director reads red/green per PR head natively.
Action-run status (list runs + per-run conclusion) - native, so re-run decisions do not depend on the specgen exec-bridge.
Rerun of a failed run - native ward tool (this also retires the swagger gap that agentic-os#434 hit: the pinned swagger has no rerun operationId, so the durable home is ward, not a specgen overlay).

Gate every one of these by ward's embedded role permission system, keyed to the mode model:

pull-request mode -> the director may merge.
pull-requests-and-merge mode -> the engineer self-merges.
branch mode -> merge withheld.

Audit ward agent director merge and the broker for any current dependence on the specgen ward ops forgejo verbs for merge/status, and cut it over to the native client so a stripped or absent .ward/ bundle cannot disable merge.

Acceptance

A director surface merges PRs, reads combined CI status, and reruns failed runs with the coilyco .ward/ specgen bundle absent or rolled back, proving zero runtime-specgen dependency.
The capability is gated by ward's embedded role/mode permission system (director merges in pull-request, engineer in pull-requests-and-merge, neither in branch), not by a guardfile leaf.
ward exec test covers merge/status/rerun gating per role x mode.

Context

Directed by Kai on 2026-07-10: "merging is a ward scale capability ... ward scale capabilities should not rely on any degree of KDL specgen at runtime ... every tool you need to manage PR workflows needs to be written into ward (probably the broker) and gated by ward's permissions systems." The specgen pr merge grant in agentic-os#446 is a legitimate also (custom-layer convenience), not the foundation - this issue is the foundation. Refs: agentic-os#446 (specgen also-grant), agentic-os#434 (rerun swagger gap), infrastructure#538 (the rollback fallout that exposed the coupling), .ward/roles.kdl (role-preset ownership note).

## Principle PR-workflow management (merge, CI status read, run status, rerun) is a **foundational ward-scale capability**, so it must be implemented as **native ward code gated by ward's own permission system** - and must **not depend on any runtime KDL specgen**. Specgen (`ward ops forgejo ...` rendered from the swagger + coilyco `.ward/` guardfiles) is the meld/custom layer. A foundational ward capability reaching up into it is the config-inversion the config-placement law forbids, and it is exactly why the 2026-07-10 permissions rollback could silently strip a director's ability to complete work (see infrastructure#538 fallout: a director surface could see the merge-ready PR wave but could neither read per-PR CI status nor merge). The role **presets** (capabilities / modes / posture) already live embedded in ward's tree - `roles.kdl` says so explicitly ("The role presets ... are ward-embedded product data and live in ward's tree, not in this overlay"). Merge authority belongs there, next to the director/engineer role definitions, not in the specgen overlay. ## Do Implement the director's PR-workflow tools as native ward capabilities, most likely in the dispatch broker alongside the existing `ward agent director merge` composite: - **Merge** (`POST /repos/{owner}/{repo}/pulls/{index}/merge`) + merged-state check - performed through ward's own compiled Forgejo client, not by shelling to `ward ops forgejo pr merge`. - **Combined CI status read** (`GET /repos/{owner}/{repo}/commits/{ref}/status`) - so the director reads red/green per PR head natively. - **Action-run status** (list runs + per-run conclusion) - native, so re-run decisions do not depend on the specgen exec-bridge. - **Rerun** of a failed run - native ward tool (this also retires the swagger gap that agentic-os#434 hit: the pinned swagger has no rerun operationId, so the durable home is ward, not a specgen overlay). Gate every one of these by ward's **embedded role permission system**, keyed to the mode model: - `pull-request` mode -> the **director** may merge. - `pull-requests-and-merge` mode -> the **engineer** self-merges. - `branch` mode -> merge withheld. Audit `ward agent director merge` and the broker for any current dependence on the specgen `ward ops forgejo` verbs for merge/status, and cut it over to the native client so a stripped or absent `.ward/` bundle cannot disable merge. ## Acceptance - A director surface merges PRs, reads combined CI status, and reruns failed runs with the coilyco `.ward/` specgen bundle **absent or rolled back**, proving zero runtime-specgen dependency. - The capability is gated by ward's embedded role/mode permission system (director merges in `pull-request`, engineer in `pull-requests-and-merge`, neither in `branch`), not by a guardfile leaf. - `ward exec test` covers merge/status/rerun gating per role x mode. ## Context Directed by Kai on 2026-07-10: "merging is a ward scale capability ... ward scale capabilities should not rely on any degree of KDL specgen at runtime ... every tool you need to manage PR workflows needs to be written into ward (probably the broker) and gated by ward's permissions systems." The specgen `pr merge` grant in agentic-os#446 is a legitimate **also** (custom-layer convenience), not the foundation - this issue is the foundation. Refs: agentic-os#446 (specgen also-grant), agentic-os#434 (rerun swagger gap), infrastructure#538 (the rollback fallout that exposed the coupling), `.ward/roles.kdl` (role-preset ownership note).

coilyco-ops added the

headless

labels

2026-07-10 18:03:22 +00:00

coilyco-ops commented

2026-07-10 18:03:35 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-claude-ward-1067 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness claude (reserved 2026-07-10T18:03:34Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#1067 · branch issue-1067 · harness claude · workflow pull-requests-and-merge
Run: engineer-claude-ward-1067 · ward v0.584.0 · dispatched 2026-07-10T18:03:34Z
Comment thread: 0 included in the pre-flight read, 0 stripped (ward's own automated comments).

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.584.0).

— Claude (she/her), via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-claude-ward-1067` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness claude` (reserved 2026-07-10T18:03:34Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#1067` · branch `issue-1067` · harness `claude` · workflow `pull-requests-and-merge` - **Run:** `engineer-claude-ward-1067` · ward `v0.584.0` · dispatched `2026-07-10T18:03:34Z` - **Comment thread:** 0 included in the pre-flight read, 0 stripped (ward's own automated comments). Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.584.0). </details> </details>  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-10 18:30:41 +00:00

Author

Member

Scope addition (Kai): PR close/reopen is a foundational director-completion capability too, same class as merge — include it in the native ward broker PR-workflow set (merge / close / reopen / commit-status / run-status / rerun), gated by ward's embedded role permission system. Today the director has no native close: ward ops forgejo pr is view/list only, and closing a PR only works via the issue close side-door on the shared index.

Scope addition (Kai): **PR close/reopen is a foundational director-completion capability too**, same class as merge — include it in the native ward broker PR-workflow set (merge / close / reopen / commit-status / run-status / rerun), gated by ward's embedded role permission system. Today the director has no native close: `ward ops forgejo pr` is view/list only, and closing a PR only works via the `issue close` side-door on the shared index.

coilyco-ops referenced this issue from a pull request that will close it,

2026-07-10 18:49:07 +00:00

Native PR-workflow tools (merge/status/rerun) gated by ward's embedded permission system #1075

coilysiren closed this issue

2026-07-10 18:49:57 +00:00

coilyco-ops commented

2026-07-10 18:50:27 +00:00

Author

Member

WARD-OUTCOME: merge-ready

details

workflow: pull-requests-and-merge; review summary: review gate skipped by ~/.ward/config.yaml default

The in-container review gate was intentionally skipped because review gate skipped by ~/.ward/config.yaml default.

PR: #1075 (closes #1067, ward.workflow: pull-requests-and-merge, CI green: test / test (pull_request) = success on head 927b1b0e).

What landed. ward agent pr status|merge|runs|rerun as compiled ward code on the core Forgejo client: broker actions pr-status/pr-merge/ci-runs/ci-rerun for the read-only director surface (host re-checks the gate), a merge-authority grant embedded in the shipped role presets KDL (director merges under pull-requests + pull-requests-and-merge, engineer self-merges under pull-requests-and-merge, patch-only/direct-main withhold; rerun needs engineering|project-management; unknown roles fail closed), head-pinned merge with live required-status gate and merged-state check, and a smart-defaults-guard exemption so the pr verb stays reachable with the coilyco bundle absent. Tests cover the role x mode matrix; docs/agent-pr-workflow.md + FEATURES entry added.

How it felt. The design fell out cleanly once the audit showed the host-side director merge was already native and the real gap was the surface: the dispatch broker already had the right channel shape (stop/list/logs), so the four actions rode it naturally. Live verification earned its keep three times: (1) the ward agent smart-defaults guard blocked the new verbs in exactly the bundle-absent scenario the issue targets - fixed with a meta-verb exemption; (2) live Forgejo marshals per-context commit status under status, not state, which meant the day-old directorMergeStatusGate would have refused every merge on the live forge - fixed version-tolerantly; (3) /actions/runs ignores limit unless page rides along.

Surprises. The live forge (Forgejo 15.0.2, gitea-1.22 API) has no Actions rerun endpoint at all, and web routes reject token auth (verified empirically), so no credentialed caller can rerun today - the native tool tries the future API leaf and degrades loudly with the retrigger fallback, which is the honest ceiling of "native rerun" until the forge ships it (agentic-os#434). Also the shared VM disk hit 100% mid-build twice; recovered without touching shared caches.

Confidence. High on the permission table, broker actions, and status/merge paths (unit-pinned on live payload shapes + live-driven reads/denials). Medium on the rerun path by construction - it cannot be exercised end-to-end against this forge version.

Follow-ups worth filing. (a) The status vs state fix suggests auditing other day-old status consumers when the forge upgrades; (b) when Forgejo ships a rerun API, the compiled client should light up unchanged - worth a smoke test then; (c) the stale "kept in sync with entrypoint.sh" note on readOnlyContextBlock predates this change and could be tidied.

WARD-OUTCOME: merge-ready <details><summary>details</summary> workflow: pull-requests-and-merge; review summary: review gate skipped by ~/.ward/config.yaml default The in-container review gate was intentionally skipped because review gate skipped by ~/.ward/config.yaml default. PR: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/pulls/1075 (closes #1067, ward.workflow: pull-requests-and-merge, CI green: test / test (pull_request) = success on head 927b1b0e). **What landed.** `ward agent pr status|merge|runs|rerun` as compiled ward code on the core Forgejo client: broker actions pr-status/pr-merge/ci-runs/ci-rerun for the read-only director surface (host re-checks the gate), a `merge-authority` grant embedded in the shipped role presets KDL (director merges under pull-requests + pull-requests-and-merge, engineer self-merges under pull-requests-and-merge, patch-only/direct-main withhold; rerun needs engineering|project-management; unknown roles fail closed), head-pinned merge with live required-status gate and merged-state check, and a smart-defaults-guard exemption so the `pr` verb stays reachable with the coilyco bundle absent. Tests cover the role x mode matrix; docs/agent-pr-workflow.md + FEATURES entry added. **How it felt.** The design fell out cleanly once the audit showed the host-side director merge was already native and the real gap was the surface: the dispatch broker already had the right channel shape (stop/list/logs), so the four actions rode it naturally. Live verification earned its keep three times: (1) the `ward agent` smart-defaults guard blocked the new verbs in exactly the bundle-absent scenario the issue targets - fixed with a meta-verb exemption; (2) live Forgejo marshals per-context commit status under `status`, not `state`, which meant the day-old directorMergeStatusGate would have refused every merge on the live forge - fixed version-tolerantly; (3) `/actions/runs` ignores `limit` unless `page` rides along. **Surprises.** The live forge (Forgejo 15.0.2, gitea-1.22 API) has no Actions rerun endpoint at all, and web routes reject token auth (verified empirically), so no credentialed caller can rerun today - the native tool tries the future API leaf and degrades loudly with the retrigger fallback, which is the honest ceiling of "native rerun" until the forge ships it (agentic-os#434). Also the shared VM disk hit 100% mid-build twice; recovered without touching shared caches. **Confidence.** High on the permission table, broker actions, and status/merge paths (unit-pinned on live payload shapes + live-driven reads/denials). Medium on the rerun path by construction - it cannot be exercised end-to-end against this forge version. **Follow-ups worth filing.** (a) The `status` vs `state` fix suggests auditing other day-old status consumers when the forge upgrades; (b) when Forgejo ships a rerun API, the compiled client should light up unchanged - worth a smoke test then; (c) the stale "kept in sync with entrypoint.sh" note on readOnlyContextBlock predates this change and could be tidied. </details>

coilysiren reopened this issue

2026-07-10 19:04:20 +00:00

coilyco-ops commented

2026-07-14 06:56:24 +00:00

Author

Member

WARDED_WORKFLOW: reservation-held

reservation details

Holder: launch intent for container engineer-codex-ward-1067 on host kais-macbook-pro-2.local.

Accepted by ward agent --harness codex (reserved 2026-07-14T06:56:23Z). Concurrent ward agent runs are blocked until this intent becomes visible or the intent is released. The stale-intent fallback is still TTL-bounded (3h TTL). --override-reservation overrides.

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#1067 · branch issue-1067 · harness codex · workflow pull-request-and-merge
Run: engineer-codex-ward-1067 · ward v0.667.0 · dispatched 2026-07-14T06:56:18Z
Comment thread: 2 included in the pre-flight read, 1 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-10T18:30:41Z), @coilyco-ops (2026-07-10T18:50:27Z)
- stripped: @coilyco-ops (2026-07-10T18:03:35Z)

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.667.0).

— Codex, via ward agent

WARDED_WORKFLOW: reservation-held <details><summary>reservation details</summary> Holder: launch intent for container `engineer-codex-ward-1067` on host `kais-macbook-pro-2.local`. Accepted by `ward agent --harness codex` (reserved 2026-07-14T06:56:23Z). Concurrent `ward agent` runs are blocked until this intent becomes visible or the intent is released. The stale-intent fallback is still TTL-bounded (3h TTL). `--override-reservation` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#1067` · branch `issue-1067` · harness `codex` · workflow `pull-request-and-merge` - **Run:** `engineer-codex-ward-1067` · ward `v0.667.0` · dispatched `2026-07-14T06:56:18Z` - **Comment thread:** 2 included in the pre-flight read, 1 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-10T18:30:41Z), @coilyco-ops (2026-07-10T18:50:27Z) - stripped: @coilyco-ops (2026-07-10T18:03:35Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.667.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops commented

2026-07-14 06:58:38 +00:00

Author

Member

WARDED_WORKFLOW: #1075

details

workflow: pull-request-and-merge; review summary: review gate skipped by ~/.ward/config.yaml default

The in-container review gate was intentionally skipped because review gate skipped by ~/.ward/config.yaml default.

PR: #1075 (closes #1067, ward.workflow: pull-requests-and-merge).

This felt like a verification pass rather than a code change because the feature was already merged upstream when this container started. Confidence is high. No surprises.

WARDED_WORKFLOW: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/pulls/1075 <details><summary>details</summary> workflow: pull-request-and-merge; review summary: review gate skipped by ~/.ward/config.yaml default The in-container review gate was intentionally skipped because review gate skipped by ~/.ward/config.yaml default. PR: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/pulls/1075 (closes #1067, ward.workflow: pull-requests-and-merge). This felt like a verification pass rather than a code change because the feature was already merged upstream when this container started. Confidence is high. No surprises. </details>

coilyco-ops closed this issue

2026-07-14 06:59:34 +00:00