Stop committing the upstream Forgejo swagger spec in aos

coilyco-ops commented

2026-07-10 10:52:17 +00:00

Member

Problem

The coilyco ward-specs bundle currently commits the upstream Forgejo OpenAPI lockfile directly at:

.ward/forgejo.swagger.lock.json

That file is about 810K and is an upstream API artifact, not authored coilyco configuration. Kai wants to remove the need to commit that upstream swagger spec into agentic-os.

Current coupling observed from the read-only director surface on 2026-07-10 UTC:

$ rg -n "forgejo\\.swagger\\.lock|forgejo\\.swagger\\.v1|spec forgejo" .ward docs scripts agentic_os tests
.ward/ward-kdl.forgejo.guardfile.kdl:11:    spec forgejo.swagger.v1.json
.ward/ward-kdl.forgejo.read.guardfile.kdl:19:    spec forgejo.swagger.v1.json
agentic_os/pre_commit/check_ward_specs_bundle.py:52:    "./forgejo.swagger.lock.json",

$ ls -lh .ward/forgejo.swagger.lock.json
-r--r--r-- 1 ubuntu ubuntu 810K ... .ward/forgejo.swagger.lock.json

The bundle-shape validator currently requires the lockfile in the release tarball:

EXPECTED_TAR_MEMBERS = (
    "./forgejo-actions-logs.sh",
    "./forgejo.swagger.lock.json",
    "./specverb.lock",
    ...
)

This also interacts with agentic-os#434: adding a missing guarded Actions task/run rerun command should not make the committed upstream swagger blob more entrenched.

Do

Remove .ward/forgejo.swagger.lock.json as a committed source artifact.
Preserve the ability for ward ops forgejo guardfiles to resolve the Forgejo OpenAPI spec deterministically.
Keep authored coilyco guardfiles and local overlays in aos, but source the upstream Forgejo spec from a generated/cache/build input rather than tracking the whole upstream spec in git.
Update agentic_os/pre_commit/check_ward_specs_bundle.py so the release bundle shape no longer requires ./forgejo.swagger.lock.json as a committed/tarred member unless the chosen design proves the release artifact must still carry a generated copy.
Update docs/ward-specs.md to describe where the upstream Forgejo spec comes from and what remains authored in aos.
Coordinate with agentic-os#434: if adding the Actions rerun route needs a local overlay for a route missing from upstream swagger, keep that overlay small and authored instead of committing a full rewritten upstream swagger file.

Acceptance

.ward/forgejo.swagger.lock.json is deleted from git or replaced by a small authored pointer/overlay file, not an 810K upstream spec blob.
ward ops forgejo describe and ward ops forgejo tasks --help still work from a fresh checkout or fail with an actionable fetch/generation message that names the missing spec source.
The ward-specs release packaging and check-ward-specs-bundle no longer require committing the upstream swagger blob.
docs/ward-specs.md documents the new source-of-truth boundary for upstream spec input versus coilyco-authored guardfiles.
Repo validation passes, or the issue comment names the exact remaining blocker and any ward-side follow-up that is required.

Related: coilyco-flight-deck/agentic-os#434 and the current ward CI/specgen cleanup.

## Problem The coilyco ward-specs bundle currently commits the upstream Forgejo OpenAPI lockfile directly at: ```text .ward/forgejo.swagger.lock.json ``` That file is about 810K and is an upstream API artifact, not authored coilyco configuration. Kai wants to remove the need to commit that upstream swagger spec into `agentic-os`. Current coupling observed from the read-only director surface on 2026-07-10 UTC: ```text $ rg -n "forgejo\\.swagger\\.lock|forgejo\\.swagger\\.v1|spec forgejo" .ward docs scripts agentic_os tests .ward/ward-kdl.forgejo.guardfile.kdl:11: spec forgejo.swagger.v1.json .ward/ward-kdl.forgejo.read.guardfile.kdl:19: spec forgejo.swagger.v1.json agentic_os/pre_commit/check_ward_specs_bundle.py:52: "./forgejo.swagger.lock.json", $ ls -lh .ward/forgejo.swagger.lock.json -r--r--r-- 1 ubuntu ubuntu 810K ... .ward/forgejo.swagger.lock.json ``` The bundle-shape validator currently requires the lockfile in the release tarball: ```python EXPECTED_TAR_MEMBERS = ( "./forgejo-actions-logs.sh", "./forgejo.swagger.lock.json", "./specverb.lock", ... ) ``` This also interacts with `agentic-os#434`: adding a missing guarded Actions task/run rerun command should not make the committed upstream swagger blob more entrenched. ## Do * Remove `.ward/forgejo.swagger.lock.json` as a committed source artifact. * Preserve the ability for `ward ops forgejo` guardfiles to resolve the Forgejo OpenAPI spec deterministically. * Keep authored coilyco guardfiles and local overlays in aos, but source the upstream Forgejo spec from a generated/cache/build input rather than tracking the whole upstream spec in git. * Update `agentic_os/pre_commit/check_ward_specs_bundle.py` so the release bundle shape no longer requires `./forgejo.swagger.lock.json` as a committed/tarred member unless the chosen design proves the release artifact must still carry a generated copy. * Update `docs/ward-specs.md` to describe where the upstream Forgejo spec comes from and what remains authored in aos. * Coordinate with `agentic-os#434`: if adding the Actions rerun route needs a local overlay for a route missing from upstream swagger, keep that overlay small and authored instead of committing a full rewritten upstream swagger file. ## Acceptance * `.ward/forgejo.swagger.lock.json` is deleted from git or replaced by a small authored pointer/overlay file, not an 810K upstream spec blob. * `ward ops forgejo describe` and `ward ops forgejo tasks --help` still work from a fresh checkout or fail with an actionable fetch/generation message that names the missing spec source. * The ward-specs release packaging and `check-ward-specs-bundle` no longer require committing the upstream swagger blob. * `docs/ward-specs.md` documents the new source-of-truth boundary for upstream spec input versus coilyco-authored guardfiles. * Repo validation passes, or the issue comment names the exact remaining blocker and any ward-side follow-up that is required. Related: coilyco-flight-deck/agentic-os#434 and the current ward CI/specgen cleanup.

coilyco-ops added the

headless

P1

labels

2026-07-10 10:52:17 +00:00

coilyco-ops commented

2026-07-10 10:52:31 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-agentic-os-435 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-10T10:52:30Z). 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/agentic-os#435 · branch issue-435 · harness codex · workflow pull-requests-and-merge
Run: engineer-codex-agentic-os-435 · ward v0.580.0 · dispatched 2026-07-10T10:52:30Z
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.580.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-agentic-os-435` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T10:52:30Z). 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/agentic-os#435` · branch `issue-435` · harness `codex` · workflow `pull-requests-and-merge` - **Run:** `engineer-codex-agentic-os-435` · ward `v0.580.0` · dispatched `2026-07-10T10:52:30Z` - **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.580.0). </details> </details>  — Codex, via `ward agent`

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

2026-07-10 11:04:55 +00:00

Stop committing the upstream Forgejo swagger spec in aos #437

coilyco-ops commented

2026-07-10 11:11:56 +00:00

Author

Member

WARD-OUTCOME: blocked 🛑

details

workflow: pull-requests-and-merge; review summary: skipped by ~/.ward/config.yaml default Blocker: Forgejo `ci / gate` failed twice on PR #437, each time after `Repo test gate`. Local `ward exec test` and `ward exec pre-commit-all` pass on this tree. The Forgejo job log route returned 404 for runs 918 and 922, so the failing step output is not visible from the run UI. Follow-up: inspect the Forgejo runner or job-log plumbing, or rerun the PR gate once logs are reachable.

WARD-OUTCOME: blocked 🛑 <details><summary>details</summary> workflow: pull-requests-and-merge; review summary: skipped by ~/.ward/config.yaml default Blocker: Forgejo `ci / gate` failed twice on PR #437, each time after `Repo test gate`. Local `ward exec test` and `ward exec pre-commit-all` pass on this tree. The Forgejo job log route returned 404 for runs 918 and 922, so the failing step output is not visible from the run UI. Follow-up: inspect the Forgejo runner or job-log plumbing, or rerun the PR gate once logs are reachable. </details>

coilyco-ops referenced this issue

2026-07-10 11:22:35 +00:00

Reshape the ward-specs bundle: restore per-harness role overrides + remove the brittle validator/test and wildcard the release tar list #438

coilyco-ops commented

2026-07-10 16:21:26 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-agentic-os-435 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-10T16:21:25Z). 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/agentic-os#435 · branch issue-435 · harness codex · workflow pull-requests-and-merge
Run: engineer-codex-agentic-os-435 · ward v0.583.0 · dispatched 2026-07-10T16:21:25Z
Comment thread: 1 included in the pre-flight read, 1 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-10T11:11:56Z)
- stripped: @coilyco-ops (2026-07-10T10:52:31Z)

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

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-agentic-os-435` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T16:21:25Z). 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/agentic-os#435` · branch `issue-435` · harness `codex` · workflow `pull-requests-and-merge` - **Run:** `engineer-codex-agentic-os-435` · ward `v0.583.0` · dispatched `2026-07-10T16:21:25Z` - **Comment thread:** 1 included in the pre-flight read, 1 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-10T11:11:56Z) - stripped: @coilyco-ops (2026-07-10T10:52:31Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.583.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops commented

2026-07-10 16:39:38 +00:00

Author

Member

WARD-OUTCOME: merge-ready

details

review summary: review gate skipped by ~/.ward/config.yaml default workflow: pull-requests-and-merge; review summary: review gate skipped by ~/.ward/config.yaml default felt: mostly merge conflict resolution, then CI-only path repairs confidence: high surprises: Forgejo checked out under /workspace/coilyco-flight-deck/agentic-os, not the older /workspace/agentic-os path follow-ups: none

WARD-OUTCOME: merge-ready <details><summary>details</summary> review summary: review gate skipped by ~/.ward/config.yaml default workflow: pull-requests-and-merge; review summary: review gate skipped by ~/.ward/config.yaml default felt: mostly merge conflict resolution, then CI-only path repairs confidence: high surprises: Forgejo checked out under /workspace/coilyco-flight-deck/agentic-os, not the older /workspace/agentic-os path follow-ups: none </details>

coilyco-ops commented

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

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-agentic-os-435 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-10T18:03:43Z). 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/agentic-os#435 · branch issue-435 · harness codex · workflow pull-requests-and-merge
Run: engineer-codex-agentic-os-435 · ward v0.584.0 · dispatched 2026-07-10T18:03:43Z
Comment thread: 2 included in the pre-flight read, 2 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-10T11:11:56Z), @coilyco-ops (2026-07-10T16:39:38Z)
- stripped: @coilyco-ops (2026-07-10T10:52:31Z), @coilyco-ops (2026-07-10T16:21:26Z)

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

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-agentic-os-435` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T18:03:43Z). 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/agentic-os#435` · branch `issue-435` · harness `codex` · workflow `pull-requests-and-merge` - **Run:** `engineer-codex-agentic-os-435` · ward `v0.584.0` · dispatched `2026-07-10T18:03:43Z` - **Comment thread:** 2 included in the pre-flight read, 2 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-10T11:11:56Z), @coilyco-ops (2026-07-10T16:39:38Z) - stripped: @coilyco-ops (2026-07-10T10:52:31Z), @coilyco-ops (2026-07-10T16:21:26Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.584.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops referenced this issue from a commit

2026-07-10 18:17:47 +00:00

fix: stop committing upstream forgejo swagger spec closes #435

coilyco-ops closed this issue

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

coilyco-ops commented

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

Author

Member

WARD-OUTCOME: merge-ready

details

review summary: review gate skipped by ~/.ward/config.yaml default
workflow: pull-requests-and-merge; review summary: review gate skipped by ~/.ward/config.yaml default
felt: merge conflict resolution, cache recovery, and merge API verification
confidence: high
surprises: Forgejo merge needed Do=merge, and pre-commit needed Go cache cleanup before warp vet could finish
follow-ups: none

WARD-OUTCOME: merge-ready <details><summary>details</summary> review summary: review gate skipped by ~/.ward/config.yaml default workflow: pull-requests-and-merge; review summary: review gate skipped by ~/.ward/config.yaml default felt: merge conflict resolution, cache recovery, and merge API verification confidence: high surprises: Forgejo merge needed Do=merge, and pre-commit needed Go cache cleanup before warp vet could finish follow-ups: none </details>

coilysiren referenced this issue from coilyco-flight-deck/ward

2026-07-14 15:27:09 +00:00

director should emit colorized, space buffered, visually distinct messages about the categories of actions its performing on startup #1283

Rows
Columns

Stop committing the upstream Forgejo swagger spec in aos #435

Problem

Do

Acceptance