docs(architecture): mark Shifts build status current in §10

agent-builder commented

2026-08-27 19:39:26 +00:00

Member

No description provided.

agent-builder added 1 commit

2026-08-27 19:39:26 +00:00

docs(architecture): mark Shifts build status current in §10

On Pull Request / checks (pull_request) Successful in 1m25s

Details

6aecc7c6e4

The §10 banner and §10.6 build-status rows still said the shift machinery
was unbuilt and nothing drove it. Shift orchestration now runs in
production: shiftengine drives rounds, the review loop, and close/settle;
worker composes role-aware writer vs review-only prompts; the Forgejo
provider posts round findings to the PR; Vikunja comment write-backs are
live when configured; the chart renders one ScaledJob/CronJob per
(team, role); per-run push credentials are built in forgebroker.

Co-authored-by: openhands <openhands@all-hands.dev>
VIK-777
Agent-Trace-Id: ploeg-cadab95cf4b4

agent-builder commented

2026-08-27 19:46:25 +00:00

Author

Member

reviewer — round 2

Docs-only §10 update matches the ticket and every pointer verifies against the code; approve.

Review of PR #44 (agent/vik-777 -> development) — VIK-777

Change under review: git diff development...agent/vik-777 = one commit (6aecc7c docs(architecture): mark Shifts build status current in §10) touching only docs/architecture.md (9 insertions, 9 deletions). Scope per ticket honoured.

Verified against the code — every row and pointer checks out

§10 banner (docs/architecture.md:453-456): now reads "The shift machinery now runs in production". Supported: CHANGELOG v0.2.0-rc.14 cites "three defects found by running rc.13 in production"; §9 items 2/4/6/18/19 mark the shift engine, role-aware prompts, tracker write-backs and the review loop closed; and this very run is a shift-orchestrated review (VIK-777), so the machinery is live. The removed "Everything in §§1–9 above is what actually runs today" was the stale half of the pair.
ploegd orchestration (architecture.md:621): pkg/shiftengine/engine.go — EnsureShift opens Shifts, evaluate opens Rounds, close closes/settles (Store.CloseShift/Store.SettleItem); reviewloop.go implements the review loop (nextFixRound, requestsChanges). Accurate.
Role-aware TaskSpec (architecture.md:622): pkg/worker/worker.go:239-251 builds TaskSpec{Role: claimed.Role, Briefing: claimed.Briefing}; pkg/worker/task.go:27 ComposePrompt(…, writes, priorPR, onReviewBranch) emits a distinct "Delivery contract (review only)" for readers vs the writer contract, and writeBriefing (task.go:133) injects round findings. Accurate.
Forgejo ForgeProvider / blackboard (architecture.md:623): pkg/provider/forgejo/forgejo.go:68 Comment posts to a PR thread; pkg/shiftengine/publish.go:114 publishes per-round findings via fp.Comment (posted at round end, not at close). Accurate.
Vikunja write-backs (architecture.md:624): cmd/ploegd/main.go:96-103 gates the provider on PLOEG_VIKUNJA_URL/_TOKEN; pkg/provider/vikunja/vikunja.go:224 Comment is live when configured(); pkg/shiftengine/publish.go:187 always calls SetStatus(…, StateNeedsHuman) and the provider (vikunja.go:239) drops anything that is not done, so "SetStatus stays a deliberate no-op (Ploeg never marks a ticket done)" is accurate for every real call path. (Author's PR-body caveat is correct: the provider could write done:true if handed StateDone — TestSetStatus_OnlyDoneIsWritten — but the only caller never does.)
Role-partitioned Helm workloads (architecture.md:625): ops/helm/ploeg/templates/scaledjob.yaml and cronjob.yaml both range over executor.teams × ploeg.teamRoles emitting one workload per (team, role). Accurate.
Per-Run push credentials (architecture.md:626): pkg/forgebroker implements Broker.Mint/Revoke + Sweeper; cmd/ploegd/main.go:192 opt-in via PLOEG_FORGEJO_ADMIN_TOKEN; ops/helm/ploeg/values.yaml:151 adminTokenSecret: {} (and deployment.yaml:97-103 renders the env var only under .with .adminTokenSecret) — so "not yet enabled in the reference deployment" is accurate.

Style / consistency

All six rows keep the table's **built** — short pointer shape and the anchor link #106-build-status resolves. The Vikunja row keeps the "deliberate no-op" nuance rather than overstating "built". Commit is docs: type with the VIK-777 trailer (no rc cut).

Observations (non-blocking, not introduced by this change)

§9 item 15 is stale (docs/architecture.md:283-287): it still claims provider.ForgeProvider has "zero implementations", which now sits two sections above a §10.6 row asserting pkg/provider/forgejo is built — and §9 item 1 already said the same thing the new row does. Out of scope for this docs-only ticket, but worth a follow-up so §9 and §10 do not disagree.
The banner's "runs in production" is a deployment-fact claim not fully provable from this repo alone; it is consistent with the CHANGELOG and §9's live-cluster references, and it matches the ticket instruction.

Verdict

approve — the change is exactly what the ticket asked for, docs-only, and every pointer it adds verifies against the code. Nothing must change before merge.

_{Posted by Ploeg on behalf of the reviewing agent. It could not push to this branch.}

### reviewer — round 2 _Docs-only §10 update matches the ticket and every pointer verifies against the code; approve._ ## Review of PR #44 (agent/vik-777 -> development) — VIK-777 Change under review: `git diff development...agent/vik-777` = one commit (`6aecc7c docs(architecture): mark Shifts build status current in §10`) touching **only** `docs/architecture.md` (9 insertions, 9 deletions). Scope per ticket honoured. ### Verified against the code — every row and pointer checks out - **§10 banner** (`docs/architecture.md:453-456`): now reads "The shift machinery now runs in production". Supported: CHANGELOG v0.2.0-rc.14 cites "three defects found by running rc.13 in production"; §9 items 2/4/6/18/19 mark the shift engine, role-aware prompts, tracker write-backs and the review loop **closed**; and this very run is a shift-orchestrated review (VIK-777), so the machinery is live. The removed "Everything in §§1–9 above is what actually runs today" was the stale half of the pair. - **ploegd orchestration** (`architecture.md:621`): `pkg/shiftengine/engine.go` — `EnsureShift` opens Shifts, `evaluate` opens Rounds, `close` closes/settles (`Store.CloseShift`/`Store.SettleItem`); `reviewloop.go` implements the review loop (`nextFixRound`, `requestsChanges`). Accurate. - **Role-aware TaskSpec** (`architecture.md:622`): `pkg/worker/worker.go:239-251` builds `TaskSpec{Role: claimed.Role, Briefing: claimed.Briefing}`; `pkg/worker/task.go:27` `ComposePrompt(…, writes, priorPR, onReviewBranch)` emits a distinct "Delivery contract (review only)" for readers vs the writer contract, and `writeBriefing` (task.go:133) injects round findings. Accurate. - **Forgejo ForgeProvider / blackboard** (`architecture.md:623`): `pkg/provider/forgejo/forgejo.go:68` `Comment` posts to a PR thread; `pkg/shiftengine/publish.go:114` publishes per-round findings via `fp.Comment` (posted at round end, not at close). Accurate. - **Vikunja write-backs** (`architecture.md:624`): `cmd/ploegd/main.go:96-103` gates the provider on `PLOEG_VIKUNJA_URL`/`_TOKEN`; `pkg/provider/vikunja/vikunja.go:224` `Comment` is live when `configured()`; `pkg/shiftengine/publish.go:187` always calls `SetStatus(…, StateNeedsHuman)` and the provider (`vikunja.go:239`) drops anything that is not `done`, so "SetStatus stays a deliberate no-op (Ploeg never marks a ticket done)" is accurate for every real call path. (Author's PR-body caveat is correct: the provider *could* write `done:true` if handed `StateDone` — `TestSetStatus_OnlyDoneIsWritten` — but the only caller never does.) - **Role-partitioned Helm workloads** (`architecture.md:625`): `ops/helm/ploeg/templates/scaledjob.yaml` and `cronjob.yaml` both `range` over `executor.teams` × `ploeg.teamRoles` emitting one workload per (team, role). Accurate. - **Per-Run push credentials** (`architecture.md:626`): `pkg/forgebroker` implements `Broker.Mint/Revoke` + `Sweeper`; `cmd/ploegd/main.go:192` opt-in via `PLOEG_FORGEJO_ADMIN_TOKEN`; `ops/helm/ploeg/values.yaml:151` `adminTokenSecret: {}` (and `deployment.yaml:97-103` renders the env var only under `.with .adminTokenSecret`) — so "not yet enabled in the reference deployment" is accurate. ### Style / consistency - All six rows keep the table's `**built** — short pointer` shape and the anchor link `#106-build-status` resolves. The Vikunja row keeps the "deliberate no-op" nuance rather than overstating "built". Commit is `docs:` type with the `VIK-777` trailer (no rc cut). ### Observations (non-blocking, not introduced by this change) - **§9 item 15 is stale** (`docs/architecture.md:283-287`): it still claims `provider.ForgeProvider` has "**zero** implementations", which now sits two sections above a §10.6 row asserting `pkg/provider/forgejo` is built — and §9 item 1 already said the same thing the new row does. Out of scope for this docs-only ticket, but worth a follow-up so §9 and §10 do not disagree. - The banner's "runs in production" is a deployment-fact claim not fully provable from this repo alone; it is consistent with the CHANGELOG and §9's live-cluster references, and it matches the ticket instruction. ### Verdict **approve** — the change is exactly what the ticket asked for, docs-only, and every pointer it adds verifies against the code. Nothing must change before merge. <sub>Posted by Ploeg on behalf of the reviewing agent. It could not push to this branch.</sub>

ryangr0 commented

2026-09-23 12:06:26 +00:00

Owner

Closing as obsolete: Glide rewrote docs/architecture.md and it no longer has the section 10 build-status table; it already states that tracker write-backs, forge operations, team plans and Shift orchestration exist. Ploeg now lives in https://forgejo.webgrip.dev/webgrip/glide under apps/ploeg; this repository is being frozen.

ryangr0 closed this pull request

2026-09-23 12:06:28 +00:00

Rows
Columns

docs(architecture): mark Shifts build status current in §10 #44