Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
5bab983
docs(prd-4173): M5 Decision Log entries before code
Nov 17, 2026
373f949
docs(prd-4173): M5 Decision Log review fixes
Nov 17, 2026
a48092a
feat(issuetracker): YouTrack State rules, MoveToColumn and State read…
Nov 17, 2026
8ce299a
fix(issuetracker): U1 review fixes (PRD 4173 M5)
Nov 17, 2026
5cd9682
fix(issuetracker): closable State decided on name alone (PRD 4173 M5 U1)
Nov 17, 2026
e1b0e9c
fix(issuetracker): state names refuse variation selectors (PRD 4173 M…
Nov 17, 2026
29f3a50
feat(forge): MoveToColumn on IssueTracker with the shared label helpe…
Nov 17, 2026
6a3dc2b
test(forge): pin AutoMove's column and refused moves in the contract …
Nov 17, 2026
68144a2
feat(issuetracker): column-to-State mapping table and route (PRD 4173…
Nov 17, 2026
0f0c78f
fix(issuetracker): bound linked column labels; NOT VALID issues CHECK…
Nov 17, 2026
fc122ee
fix(issuetracker): column labels refuse State-name fillers too (PRD 4…
Nov 17, 2026
d671bf1
fix(issuetracker): State names keep braces; labels keep the tag rule …
Nov 17, 2026
6aa48c2
fix(issuetracker): StateNameProblem doc placement; brace label refusa…
Nov 17, 2026
893c64e
feat(board): linked repo moves, close and reopen through the State fi…
Nov 17, 2026
8710f85
feat(board): MR close and reopen move a linked repo's card (PRD 4173 …
Nov 18, 2026
210c0eb
fix(board): record the column's third writer; pin the U4a gaps (PRD 4…
Nov 18, 2026
ba733c5
fix(board): an unavailable issue side still records a linked MR close…
Nov 18, 2026
6ecae44
fix(board): a transient repo-source read defers a linked MR edge (PRD…
Nov 18, 2026
9758a54
test(board): pin the repo-source read classification and the deferral…
Nov 18, 2026
4278e0c
feat(issuetracker): issues uzi creates on a linked repo carry the eli…
Nov 18, 2026
9b578c0
test(issuetracker): pin exact eligibility removal and create not-foun…
Nov 18, 2026
80c3c88
feat(issuetracker): comments and the PRD link patch reach YouTrack (P…
Nov 18, 2026
bb61c9f
docs(issuetracker): guard comments match the M5 writes; honest stub t…
Nov 18, 2026
fe6fb95
docs(issuetracker): M5 landed in the ADR, PRD and changelog (PRD 4173…
Nov 18, 2026
0cb3095
docs(issuetracker): narrow the M5 ADR and changelog claims; M5 tick n…
Nov 18, 2026
63b7d06
Merge prd/ws-2 (66b83546): M4 review fixes into the M5 branch
Nov 18, 2026
ea194d1
test(issuetracker): the run-now sweep test selects the linked eligibi…
Nov 18, 2026
558bb90
fix(issuetracker): an automatic move never reopens an issue resolved …
Nov 18, 2026
5e794b1
test(issuetracker): untagged creates stay off the board; chat and sch…
Nov 18, 2026
74dfe9c
docs(issuetracker): LinkedIssueResolved names column moves only; prop…
Nov 18, 2026
4c25607
docs(issuetracker): resolved-issue guard, U2-U4 and rework test chang…
Nov 18, 2026
710b82b
docs(issuetracker): name UpsertIssueIfChanged in the U2-U4 entry; cha…
Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 15 additions & 4 deletions adr/4173-issue-tracker-seam.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# ADR-4173: The issue tracker seam

**Status**: Accepted (PRD #4173, M4 landed; M5–M6 pending)
**Date**: 2026-11-11 (updated 2026-11-17)
**Status**: Accepted (PRD #4173, M5 landed; M6 pending)
**Date**: 2026-11-11 (updated 2026-11-18)
**Deciders**: the maintainer + agent team
**PRD**: [prds/4173-external-issue-trackers.md](../prds/4173-external-issue-trackers.md) — the PRD carries the milestones and the Decision Log; this ADR carries the durable shape of what M3 and M4 built and the invariants a later change must keep.
**PRD**: [prds/4173-external-issue-trackers.md](../prds/4173-external-issue-trackers.md) — the PRD carries the milestones and the Decision Log; this ADR carries the durable shape of what M3 to M5 built and the invariants a later change must keep.

## Decision (summary)

Issue trackers other than the repo's forge sit behind a `Driver` in their own package, `api/internal/issuetracker`. A driver is `forge.IssueTracker` plus four connection operations. Connections live apart from forge connections (`issuetrackersvc`, table `issue_tracker_connections`) with their own base URL allowlist. The YouTrack driver adapts YouTrack's string ids inside itself, is built for exactly one project, and treats tags as user-owned objects chosen by id. From M4 a repo created after the M4 migration can link to one before its first enable (D13); a repo with no link behaves as before.

Shipped in M4: the repo link and `IssueTrackerForRepo` returning the linked issue tracker, with intake and runs from YouTrack issues. Not shipped yet: issue writes and board moves on YouTrack (M5), the web and CLI settings surfaces, docs and the live pass against a real YouTrack (M6). On a linked repo every issue write is refused with `ErrIssueWriteNotOffered`.
Shipped in M4: the repo link and `IssueTrackerForRepo` returning the linked issue tracker, with intake and runs from YouTrack issues. Shipped in M5: the board and issue writes on YouTrack. A card move goes through `MoveToColumn` and writes the issue's YouTrack State, through a per-repo column-to-State mapping set with `GET` and `PUT /api/repos/{id}/issue-tracker-link/states` (session-only, no UI); an unmapped column is never guessed (`ErrColumnNotMapped`, a 409 on a board drag). Close and reopen write the stored closed, open or mapped column States, and never land on a won't-fix State: closability is an allowlist of done-style names, checked when the mapping is saved and again against the live bundle before every State write. A column move refuses an issue YouTrack already shows as resolved unless it is the explicit reopen of a closed card (`ColumnMove.Reopen`), so an automatic move or a board drag never reopens an issue a person resolved there. A linked card's board column is read from its State and cached in `issues.issue_tracker_column`. Issues uzi creates on a linked repo are created in the linked project and carry the eligibility tag where the forge path would carry the uzi label. Comments and the PRD link patch reach the issue. The one issue write still refused is removing the eligibility tag (`ErrIssueWriteNotOffered`); `EnsureRepoLabels` is refused with a 409 before any request. Not shipped yet: the web and CLI settings surfaces (the mapping has no UI), docs, the live pass against a real YouTrack, and the issue detail page's column (all M6). There is no close-on-merge: a linked MR body is non-closing, so the issue stays in its column after the merge until a person closes it.

## Context

Expand Down Expand Up @@ -59,12 +59,23 @@ Port note (2026-11-17): M4 was rebased onto the final M3. Of the M3 review chang
- **S3. Credentials follow the forge rules.** Sealed token with AAD and no reveal path, https-only base URL on the separate empty-by-default allowlist re-checked in `DriverFor`, redirects refused, errors redacted. The redirect, oversized-body and token-in-error cases each have a test in `api/internal/issuetracker`.
- **S4. Issue tracker text is untrusted input.** The driver bounds what it reads (response bytes, listing pages and items, nested items, label name length). YouTrack titles, descriptions and comments go through the same `issueinput` fencing as forge text; an oversized description is refused and an oversized comment by the connection's own account is cut to the same bound as on a forge, while an unmapped author's comment is withheld; M4 tests each.
- **S5. The worker never holds an issue tracker token.** The allowlist does not feed worker egress, and the token is opened only inside `DriverFor` in the API. The worker read routes go through the API's resolver, so the worker never holds the token.
- **S6. Every YouTrack State write re-checks the live bundle.** The open state and every column state must be unresolved and not archived, the closed state must pass `issuetracker.ClosableState` (an allowlist on the State's `name` alone, never `localizedName`), and all mapped states must be distinct. All of this runs when the mapping is saved (a 400); before every write the target State is checked again in its role, failing with `ErrStateNotAllowed`; an unmapped column fails with `ErrColumnNotMapped` before any request. Do not turn the allowlist into a denylist.
- **S7. The eligibility tag is never stripped.** The write guard refuses any label write on a linked repo that removes the link's eligibility name, and remove-label-on-dispatch compares the selector with the eligibility label. Every other issue write is lifted one operation at a time and passes through `markNotFound`, so a moved-away issue stays skippable.
- **S8. `issues.issue_tracker_column` has three writers.** The linked `UpsertIssueIfChanged`, `SetIssueTrackerColumn` (after a successful move) and `ClearIssueTrackerColumnsNotIn` (a linked `ConfigureColumns`, in the transaction that prunes the mapping). Every reader goes through `board.CardColumnLabels`, keyed on the repo being linked, which leaves an unlinked repo's labels unchanged.
- **S9. `forge.MoveByLabels` keeps the forge label calls identical.** `EnsureLabels` only when `Ensure` is non-empty, then one `UpdateIssueLabels` with the slices passed through. `forgetest.Recorder` logs `MoveToColumn` in a separate `Moves()` log so the `Calls()` goldens do not change. The YouTrack driver ignores the label fields, because columns are not tags.
- **S10. A linked run's MR-state moves happen in the board-free MR-watch lane.** It moves cards only on the close and reopen edges and only for the issue's latest issue-lane run; the board lane excludes linked repos so the two stay disjoint.

## Open questions for M6's live pass

- Whether YouTrack accepts `readSharingSettings` and `tagSharingSettings` in the tag-create body. The fake accepts them; no real server has been asked.
- Whether an authenticated token receives `usersCount` on a tag's sharing groups (the anonymous recording has none).
- Whether the id-scoped listing `GET /api/tags/{id}/issues` behaves on a real instance as the fake and YouTrack's documented shape say. The earlier question, whether `tag: {name}` resolves every tag of that name, is settled: intake sends no tag name in a search query (PRD Decision Log 2026-11-12). If the listing proves unusable, the documented fallback walks the whole project and filters by stored id, bounded by the same listing ceilings.
- Whether the real YouTrack State write (the custom field update on an issue) behaves as the fake and the documented shape say.
- Whether the bounded `State` custom field read with each issue behaves on a real instance, including the cap that fails a listing when the field list is over it.
- Whether the done-name allowlist matches real bundles. A done state named only in another language is refused, so a real project may need its State renamed or the list extended.
- Whether a non-admin token can read `admin/projects/{id}/customFields`, which the live bundle check uses before every State write.
- The window between the bundle check and the State write (as in D10): a bundle edited inside it can still be landed on.
- The duplicate-on-retry risk of a create: YouTrack's create has no rollback, so if the POST lands but attaching the tag or the read-back fails, the untagged issue stays in YouTrack and a retry can file a duplicate.

## Consequences

Expand Down
16 changes: 16 additions & 0 deletions api/internal/board/board.go
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,22 @@ func ResolveColumn(labels []string, state string, position map[string]int) (colu
return best, false, matches > 1
}

// CardColumnLabels returns the labels a column-inferring ResolveColumn call
// should read. A card of a repo linked to an issue tracker sits in the column
// cached from its State (issues.issue_tracker_column), never in a label, because
// columns are not tags there (D9, D14): it returns just that column, or nil for
// the Open lane (column ""). On any other repo it returns labels unchanged.
// linked is the repo's linkage, never a property of one issue's key.
func CardColumnLabels(linked bool, labels []string, column string) []string {
if !linked {
return labels
}
if column == "" {
return nil
}
return []string{column}
}

// PlanLabelMove computes the atomic add/remove sets for a single-column move and
// the resulting label set for the cache. add is the target column (if not
// already present); remove is every OTHER column label the issue currently
Expand Down
40 changes: 40 additions & 0 deletions api/internal/board/board_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -128,3 +128,43 @@ func TestPlanLabelMove(t *testing.T) {
})
}
}

func TestCardColumnLabels(t *testing.T) {
labels := []string{"uzi", "Planned"}
tests := []struct {
name string
linked bool
labels []string
column string
want []string
}{
{"unlinked keeps the labels", false, labels, "", labels},
{"unlinked ignores a stray cached column", false, labels, "In Progress", labels},
{"unlinked nil stays nil", false, nil, "", nil},
{"linked reads the cached column only", true, labels, "In Progress", []string{"In Progress"}},
{"linked with no cached column is the Open lane", true, labels, "", nil},
{"linked never reads a column label", true, []string{"Planned"}, "", nil},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
got := CardColumnLabels(tc.linked, tc.labels, tc.column)
if len(got) != len(tc.want) || (tc.want == nil) != (got == nil) {
t.Fatalf("CardColumnLabels = %#v, want %#v", got, tc.want)
}
for i := range got {
if got[i] != tc.want[i] {
t.Fatalf("CardColumnLabels = %#v, want %#v", got, tc.want)
}
}
})
}
// The unlinked result is the input slice itself, so ResolveColumn sees identical input.
if got := CardColumnLabels(false, labels, "x"); &got[0] != &labels[0] {
t.Fatal("an unlinked repo must get its labels back unchanged")
}
pos := map[string]int{"In Progress": 1, "Planned": 0}
col, closed, conflict := ResolveColumn(CardColumnLabels(true, labels, "In Progress"), "opened", pos)
if col != "In Progress" || closed || conflict {
t.Fatalf("ResolveColumn = %q %v %v", col, closed, conflict)
}
}
5 changes: 5 additions & 0 deletions api/internal/forge/forgejo_issues.go
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,11 @@ func (f *forgejo) UpdateIssueDescription(ctx context.Context, projectID, issueII
}{Body: description})
}

// MoveToColumn moves the issue to a board column through its labels.
func (f *forgejo) MoveToColumn(ctx context.Context, projectID, issueIID int64, move ColumnMove) error {
return MoveByLabels(ctx, f, projectID, issueIID, move)
}

// SetIssueState closes or reopens an issue.
//
// This sends a STATE-ONLY PATCH and does NOT read the issue first, for the same
Expand Down
5 changes: 5 additions & 0 deletions api/internal/forge/forgetest/basefake.go
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,11 @@ func (*BaseFake) UpdateIssueLabels(context.Context, int64, int64, []string, []st
return notStubbed("UpdateIssueLabels")
}

// MoveToColumn implements forge.Forge.
func (*BaseFake) MoveToColumn(context.Context, int64, int64, forge.ColumnMove) error {
return notStubbed("MoveToColumn")
}

// UpdateIssueDescription implements forge.Forge.
func (*BaseFake) UpdateIssueDescription(context.Context, int64, int64, string) error {
return notStubbed("UpdateIssueDescription")
Expand Down
5 changes: 3 additions & 2 deletions api/internal/forge/forgetest/basefake_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ func actionMethods() []struct {
return err
}},
{"UpdateIssueLabels", func(b *BaseFake) error { return b.UpdateIssueLabels(ctx, 1, 2, nil, nil) }},
{"MoveToColumn", func(b *BaseFake) error { return b.MoveToColumn(ctx, 1, 2, forge.ColumnMove{}) }},
{"UpdateIssueDescription", func(b *BaseFake) error { return b.UpdateIssueDescription(ctx, 1, 2, "d") }},
{"SetIssueState", func(b *BaseFake) error { return b.SetIssueState(ctx, 1, 2, forge.StateClosed) }},
{"UserExists", func(b *BaseFake) error { _, err := b.UserExists(ctx, "u"); return err }},
Expand Down Expand Up @@ -166,8 +167,8 @@ func actionMethods() []struct {

func TestBaseFakeActionMethodsNotStubbed(t *testing.T) {
methods := actionMethods()
if len(methods) != 37 {
t.Fatalf("expected 37 action methods, got %d", len(methods))
if len(methods) != 38 {
t.Fatalf("expected 38 action methods, got %d", len(methods))
}
b := &BaseFake{}
for _, m := range methods {
Expand Down
43 changes: 38 additions & 5 deletions api/internal/forge/forgetest/recorder.go
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,15 @@ import (
// the method name plus its arguments, formatted by formatArg. It exists so a
// test can pin the exact set of forge calls a code path makes (a golden
// record, see AssertGolden) and notice when a later refactor changes it.
// Only calls are recorded, never results; the wrapped Forge supplies those.
// Only calls are recorded, never results; the wrapped Forge supplies the
// results of every method except MoveToColumn.
//
// Safe for concurrent use. Calls() keeps call order.
// MoveToColumn is the exception: its line goes to Moves(), not Calls(), and it
// runs forge.MoveByLabels over the Recorder, so the wrapped Forge's own
// MoveToColumn is never called; only the EnsureLabels and UpdateIssueLabels
// calls reach it.
//
// Safe for concurrent use. Calls() and Moves() keep call order.
//
// Recorder implements only forge.Forge. It hides any optional interface the
// wrapped value also implements (for example ProjectBoardSyncer), so code that
Expand All @@ -27,8 +33,9 @@ import (
type Recorder struct {
inner forge.Forge

mu sync.Mutex // guards calls
mu sync.Mutex // guards calls and moves
calls []string
moves []string
}

var _ forge.Forge = (*Recorder)(nil)
Expand All @@ -44,17 +51,43 @@ func (r *Recorder) Calls() []string {
return append([]string(nil), r.calls...)
}

func (r *Recorder) record(method string, args ...any) {
// Moves returns a copy of the recorded MoveToColumn lines in call order. They are
// kept apart from Calls so the recorded-call goldens stay byte-identical.
func (r *Recorder) Moves() []string {
r.mu.Lock()
defer r.mu.Unlock()
return append([]string(nil), r.moves...)
}

func formatCall(method string, args ...any) string {
parts := make([]string, len(args))
for i, a := range args {
parts[i] = formatArg(reflect.ValueOf(a))
}
line := method + "(" + strings.Join(parts, ", ") + ")"
return method + "(" + strings.Join(parts, ", ") + ")"
}

func (r *Recorder) record(method string, args ...any) {
line := formatCall(method, args...)
r.mu.Lock()
r.calls = append(r.calls, line)
r.mu.Unlock()
}

// MoveToColumn records the move in Moves, not Calls, then performs the
// label-backed move over the Recorder itself, so the EnsureLabels and
// UpdateIssueLabels calls land in Calls and are delegated to the wrapped Forge
// exactly as before. It never calls the wrapped Forge's MoveToColumn: the
// recorded-call goldens stay byte-identical, and the Recorder records the
// label-backed move.
func (r *Recorder) MoveToColumn(ctx context.Context, a0 int64, a1 int64, move forge.ColumnMove) error {
line := formatCall("MoveToColumn", a0, a1, move)
r.mu.Lock()
r.moves = append(r.moves, line)
r.mu.Unlock()
return forge.MoveByLabels(ctx, r, a0, a1, move)
}

var timeType = reflect.TypeOf(time.Time{})

// formatArg renders v deterministically: times as RFC3339 UTC (zero time as
Expand Down
52 changes: 52 additions & 0 deletions api/internal/forge/forgetest/recorder_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,55 @@ func TestAssertGoldenWritesThenMatches(t *testing.T) {
}

func reflectValue(v any) reflect.Value { return reflect.ValueOf(v) }

// moveInner stubs the label writes and fails the test if the Recorder ever
// forwards MoveToColumn to it.
type moveInner struct {
BaseFake
t *testing.T
underlying []string
}

func (m *moveInner) EnsureLabels(context.Context, int64, []forge.Label) error {
m.underlying = append(m.underlying, "EnsureLabels")
return nil
}

func (m *moveInner) UpdateIssueLabels(context.Context, int64, int64, []string, []string) error {
m.underlying = append(m.underlying, "UpdateIssueLabels")
return nil
}

func (m *moveInner) MoveToColumn(context.Context, int64, int64, forge.ColumnMove) error {
m.t.Error("Recorder forwarded MoveToColumn to the wrapped Forge")
return nil
}

func TestRecorderMoveToColumnRecordsTheLabelBackedMove(t *testing.T) {
inner := &moveInner{t: t}
rec := NewRecorder(inner)
move := forge.ColumnMove{
Column: "In Progress",
Ensure: []forge.Label{{Name: "In Progress", Color: "#123456"}},
Add: []string{"In Progress"},
Remove: []string{"Planned"},
}
if err := rec.MoveToColumn(context.Background(), 42, 7, move); err != nil {
t.Fatal(err)
}

wantMoves := []string{`MoveToColumn(42, 7, {Column:"In Progress" Ensure:[{Name:"In Progress" Color:"#123456"}] Add:["In Progress"] Remove:["Planned"] Reopen:false})`}
if got := rec.Moves(); !slices.Equal(got, wantMoves) {
t.Fatalf("moves = %q, want %q", got, wantMoves)
}
wantCalls := []string{
`EnsureLabels(42, [{Name:"In Progress" Color:"#123456"}])`,
`UpdateIssueLabels(42, 7, ["In Progress"], ["Planned"])`,
}
if got := rec.Calls(); !slices.Equal(got, wantCalls) {
t.Fatalf("calls = %q, want %q", got, wantCalls)
}
if want := []string{"EnsureLabels", "UpdateIssueLabels"}; !slices.Equal(inner.underlying, want) {
t.Fatalf("wrapped calls = %v, want %v", inner.underlying, want)
}
}
5 changes: 5 additions & 0 deletions api/internal/forge/github_issues.go
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,11 @@ func (g *github) UpdateIssueDescription(ctx context.Context, projectID, issueIID
return nil
}

// MoveToColumn moves the issue to a board column through its labels.
func (g *github) MoveToColumn(ctx context.Context, projectID, issueIID int64, move ColumnMove) error {
return MoveByLabels(ctx, g, projectID, issueIID, move)
}

// SetIssueState closes or reopens an issue. go-github's UpdateIssueRequest
// leaves Title/Body nil (unchanged) and Labels/Assignees omitzero (unchanged)
// when only State and StateReason are set, so this sends the state ALONE and
Expand Down
5 changes: 5 additions & 0 deletions api/internal/forge/gitlab.go
Original file line number Diff line number Diff line change
Expand Up @@ -431,6 +431,11 @@ func (g *gitLab) UpdateIssueLabels(ctx context.Context, projectID, issueIID int6
return nil
}

// MoveToColumn moves the issue to a board column through its labels.
func (g *gitLab) MoveToColumn(ctx context.Context, projectID, issueIID int64, move ColumnMove) error {
return MoveByLabels(ctx, g, projectID, issueIID, move)
}

// SetIssueState closes or reopens an issue via GitLab's state_event verb.
// gitlab.UpdateIssueOptions.StateEvent is a *string with `omitempty` and takes
// the MUTATE vocabulary "close"/"reopen" (not the query-filter opened/closed the
Expand Down
Loading