docs: document the forge key on a routing rule #34

Open

agent-builder wants to merge 1 commit from agent/vik-629 into development

pull from: agent/vik-629

merge into: webgrip:development

webgrip:development

webgrip:fix/bump-go-deps

webgrip:main

Conversation 1 Commits 1 Files changed 1 +8

agent-builder commented 2026-07-31 05:28:04 +00:00

Member

Copy link

What / why

Ticket VIK-629 (docs): document the forge: key on a routing rule in config.trackers.vikunja.projects[].

A routing rule may name the forge instance that holds the repo via a forge: key. Until now no rule set it, every resolved Work Target carried the empty string, and publishRound looked it up as a literal registry key — so the round's reading Role findings were silently discarded. This change documents the key (what it identifies, the empty-value fallback, why it matters) in the routing section of docs/architecture.md.

Acceptance criteria

1. States forge identifies a forge instance id, not the provider dialect name.
2. States an empty/omitted value falls back to the deployment default forge id.
3. States findings publication looks the provider up by this id.
4. 2–5 sentences; no new files; no code changes.

All met — docs-only change, docs/architecture.md is the only file touched.

Evidence / gates

This is a docs-only change (one markdown paragraph) and cannot affect the Go or Helm gates. Local gate run via the DinD daemon with the CI images (golang:1.25, alpine/helm) was attempted but the worker sandbox cannot pull either image (no preloaded images, no registry mirror, egress to registry-1.docker.io times out — verified with docker pull and direct HTTPS probes). The full gate suite from .forgejo/workflows/on_pull_request.yml therefore ran on the Forgejo CI runner for this PR: On Pull Request / checks — success in 2m44s (gofmt, go vet ./..., go build ./..., go test ./..., helm lint ops/helm/ploeg, all three helm template renders, ./scripts/helm-golden.sh check).

Risk notes (self-review)

• Docs-only: no Go code, chart template, or values file touched (ticket's out-of-scope list respected).
• No money paths, concurrency, or secrets implicated.

VIK-629

## What / why Ticket **VIK-629** (docs): document the `forge:` key on a routing rule in `config.trackers.vikunja.projects[]`. A routing rule may name the forge instance that holds the repo via a `forge:` key. Until now no rule set it, every resolved Work Target carried the empty string, and `publishRound` looked it up as a literal registry key — so the round's reading Role findings were silently discarded. This change documents the key (what it identifies, the empty-value fallback, why it matters) in the routing section of `docs/architecture.md`. ## Acceptance criteria 1. States `forge` identifies a forge **instance** id, not the provider dialect name. 2. States an empty/omitted value falls back to the deployment default forge id. 3. States findings publication looks the provider up by this id. 4. 2–5 sentences; no new files; no code changes. All met — docs-only change, `docs/architecture.md` is the only file touched. ## Evidence / gates This is a docs-only change (one markdown paragraph) and cannot affect the Go or Helm gates. Local gate run via the DinD daemon with the CI images (`golang:1.25`, `alpine/helm`) was attempted but the worker sandbox cannot pull either image (no preloaded images, no registry mirror, egress to `registry-1.docker.io` times out — verified with `docker pull` and direct HTTPS probes). The full gate suite from `.forgejo/workflows/on_pull_request.yml` therefore ran on the Forgejo CI runner for this PR: **On Pull Request / checks — success in 2m44s** (gofmt, `go vet ./...`, `go build ./...`, `go test ./...`, `helm lint ops/helm/ploeg`, all three `helm template` renders, `./scripts/helm-golden.sh check`). ## Risk notes (self-review) - Docs-only: no Go code, chart template, or values file touched (ticket's out-of-scope list respected). - No money paths, concurrency, or secrets implicated. VIK-629

agent-builder added 1 commit 2026-07-31 05:28:04 +00:00

docs: document the forge key on a routing rule ... 711f9a27af

A routing rule in config.trackers.vikunja.projects[] may name the forge
instance that holds its repo via the forge: key. Document what the key
identifies, what an omitted value falls back to, and why it matters for
findings publication.

VIK-629
Agent-Trace-Id: ploeg-0028994ce137

agent-builder commented 2026-07-31 05:37:39 +00:00

Author

Member

Copy link

reviewer — round 2

Docs change for forge key met all four ACs, verified against code; approve.

Review of PR 34 / branch agent/vik-629 — VIK-629

Verdict: approve

What changed

git diff development...agent/vik-629 is exactly one file, docs/architecture.md, +8 lines
(lines 247–254, §8 "Teams and deployment knobs"). No new files, no Go code, no chart template
or values-file changes — the out-of-scope boundary is respected.

Acceptance criteria — all met

1. Forge INSTANCE id, not provider dialect — "A rule's forge: key names the forge
   instance that holds the repo — a registry id, not the provider dialect name."
   Confirmed against the code: cmd/ploegd/main.go registers the provider under the forge
   instance id and comments that id ≠ dialect name (ADR-0016); pkg/config/config.go:67-68
   and cmd/ploegd/sweep.go:144 (forgeIDFromEnv, default forgejo) use the same framing.
2. Empty/omitted falls back to the deployment default — "Omitted or empty, it falls back
   to the deployment default forge id." Confirmed: pkg/config/resolve.go:69-72 omits
   ;forge= when empty, and pkg/target/resolver.go:100-102 fills the empty id with
   defaultForge (= the deployment default, wired in cmd/ploegd/main.go:189).
3. Why it matters — "findings publication resolves the provider from this id (§10.3): a
   value matching no registry entry silently drops the round's findings instead of commenting
   on the pull request." Confirmed: pkg/shiftengine/publish.go looks up e.Forges[forgeID]
   and returns without publishing when no entry matches (lines 91–100). The §10.3
   cross-reference is where the publish-findings step appears in the loop.
4. Four sentences; no new files; no code changes — the paragraph is 4 sentences
   (within the 2–5 bound); only docs/architecture.md is touched.

Non-blocking notes (no change requested)

• §10.3 ("The full loop") shows "publish findings as PR comments" but does not itself discuss
  the forge-id registry lookup; the reference is a pointer to where publication happens rather
  than to a description of the lookup. Accurate, just loose.
• "Silently drops" is the codebase's own framing (cmd/ploegd/main.go:179; the ticket's
  description). Strictly it logs a Warn (pkg/shiftengine/publish.go:96), so the findings are
  dropped from the PR surface but not from the log — acceptable, and consistent with the
  existing docs' language.
• The commented config.trackers.vikunja.projects[] example in ops/helm/ploeg/values.yaml
  does not show a forge: line; values files are explicitly out of scope for this ticket, and
  the paragraph itself documents the key, so no gap.

What a human should re-check

Nothing structural. If desired, a follow-up could add forge: to the commented example in
ops/helm/ploeg/values.yaml (separate ticket — out of scope here).

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

### reviewer — round 2 _Docs change for forge key met all four ACs, verified against code; approve._ ## Review of PR 34 / branch agent/vik-629 — VIK-629 ### Verdict: **approve** ### What changed `git diff development...agent/vik-629` is exactly one file, `docs/architecture.md`, +8 lines (lines 247–254, §8 "Teams and deployment knobs"). No new files, no Go code, no chart template or values-file changes — the out-of-scope boundary is respected. ### Acceptance criteria — all met 1. **Forge INSTANCE id, not provider dialect** — "A rule's `forge:` key names the forge **instance** that holds the repo — a registry id, not the provider dialect name." Confirmed against the code: `cmd/ploegd/main.go` registers the provider under the forge instance id and comments that id ≠ dialect name (ADR-0016); `pkg/config/config.go:67-68` and `cmd/ploegd/sweep.go:144` (`forgeIDFromEnv`, default `forgejo`) use the same framing. 2. **Empty/omitted falls back to the deployment default** — "Omitted or empty, it falls back to the deployment default forge id." Confirmed: `pkg/config/resolve.go:69-72` omits `;forge=` when empty, and `pkg/target/resolver.go:100-102` fills the empty id with `defaultForge` (= the deployment default, wired in `cmd/ploegd/main.go:189`). 3. **Why it matters** — "findings publication resolves the provider from this id (§10.3): a value matching no registry entry silently drops the round's findings instead of commenting on the pull request." Confirmed: `pkg/shiftengine/publish.go` looks up `e.Forges[forgeID]` and `return`s without publishing when no entry matches (lines 91–100). The §10.3 cross-reference is where the publish-findings step appears in the loop. 4. **Four sentences; no new files; no code changes** — the paragraph is 4 sentences (within the 2–5 bound); only `docs/architecture.md` is touched. ### Non-blocking notes (no change requested) - §10.3 ("The full loop") shows "publish findings as PR comments" but does not itself discuss the forge-id registry lookup; the reference is a pointer to where publication happens rather than to a description of the lookup. Accurate, just loose. - "Silently drops" is the codebase's own framing (`cmd/ploegd/main.go:179`; the ticket's description). Strictly it logs a Warn (`pkg/shiftengine/publish.go:96`), so the findings are dropped from the PR surface but not from the log — acceptable, and consistent with the existing docs' language. - The commented `config.trackers.vikunja.projects[]` example in `ops/helm/ploeg/values.yaml` does not show a `forge:` line; values files are explicitly out of scope for this ticket, and the paragraph itself documents the key, so no gap. ### What a human should re-check Nothing structural. If desired, a follow-up could add `forge:` to the commented example in `ops/helm/ploeg/values.yaml` (separate ticket — out of scope here). _{Posted by Ploeg on behalf of the reviewing agent. It could not push to this branch.}

All checks were successful

Hide all checks

On Pull Request / checks (pull_request) Successful in 2m44s

Details

This pull request can be merged automatically.

This branch is out-of-date with the base branch

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin agent/vik-629:agent/vik-629

git switch agent/vik-629

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch development

git merge --no-ff agent/vik-629

git switch agent/vik-629

git rebase development

git switch development

git merge --ff-only agent/vik-629

git switch agent/vik-629

git rebase development

git switch development

git merge --no-ff agent/vik-629

git switch development

git merge --squash agent/vik-629

git switch development

git merge --ff-only agent/vik-629

git switch development

git merge agent/vik-629

git push origin development

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

webgrip/ploeg!34

No description provided.