Design: repository-scoped task keys (PROJ-REPO-N, e.g. TRIM-UI-200) for multi-repo projects #649

Follow-up to the discussion in Paca-AI/paca-plugins#34. This is a text-only proposal: I'd like agreement on the semantics before I write any code. It builds on #648 (project connections, several repositories per project).

Problem

A project can now link several repositories, possibly from different providers. Its task keys (TRIM-200) don't say which repository the work belongs to:

• An agent picking up TRIM-200 has no signal for which linked repo to work in.
• A branch or change-request title that names a task links it in every linked repo where the key appears, even when the work belongs to one repo only.
• Making the key optional doesn't fix this: a team that works for months with TRIM-200 on one repo and then links a second one ends up with ambiguous keys and two naming conventions.
• Existing bug: the matcher in service/git/service.go (taskRefRE = (?i)\b([a-z][a-z0-9]{0,9})-(\d{1,7})\b) parses TRIM-UI-200 as UI-200, because \b matches after the first hyphen. So a 3-part key today links to nothing, or to a different project whose prefix happens to be UI.

Proposal

1. Per-link repository short key (required, auto-suggested)

• New column git_repositories.short_key TEXT NOT NULL, with a check that it is never empty.
  • Unique index on (project_id, upper(short_key)).
• Format ^[A-Z][A-Z0-9]{0,9}$:
  • Uppercased, like task_id_prefix.
  • No hyphen, so parsing stays unambiguous.
  • Must not equal the project's own task_id_prefix.
• Required on every linked repository, even when the project has only one. A repository can never be in a "no key" state, so linking another repo later changes nothing for the existing ones.
• Auto-suggested in the link form, which arrives pre-filled. This mirrors how suggestPrefix pre-fills task_id_prefix. The suggestion comes from the last segment of full_path:
  • initials of -/_/.-separated words: ui-app → UA;
  • otherwise the first 4 letters: frontend → FRON;
  • a numeric suffix if the key is taken in the project: FRON2.
    The user can change the key but not clear it.
• Editable later through PATCH. Existing branch and CR links are stored rows and are kept. Only new branches using the old key stop matching, and the UI says so.
• The key belongs to the link, so the same repo can carry a different key in each project that links it.

2. Key grammar and matching

• Two forms:
  • PROJ-N: today's form, behaviour unchanged.
  • PROJ-REPO-N: new.
• REPO is a routing and validation hint, not part of the task's identity. Task numbers stay per project, so TRIM-UI-200 and TRIM-200 refer to the same task.
• A new pure parser parseTaskRefs(text) tries the 3-part form first, then the 2-part form on the remaining text, so a matched 3-part key is never re-read as UI-200.
• In saveChangeRequest, for an event on repo R of project P:
  • PROJ-N: still accepted for backward compatibility. It links in the repo the event came from, as today. Agents, branch hints and docs always use the 3-part form.
  • PROJ-REPO-N: link only when PROJ matches P's task_id_prefix and REPO matches R.short_key. A key that names another repository of the project is ignored on R.
• FindTaskByRef is reused unchanged.

3. API

• short_key is added to:
  • the link request (LinkGitRepositoryRequest / LinkInput): required in the UI; if an API call omits it, the server applies the suggestion;
  • GitRepositoryResponse;
  • the task git view (TaskChangeRequest / TaskBranch).
• New route PATCH /projects/{id}/git/repositories/{repositoryId} to set or change the key, gated by git:write.
• New errors GIT_SHORT_KEY_INVALID and GIT_SHORT_KEY_TAKEN.

4. Agents and MCP

• In the agent prompt (prompt.go):
  • The repository bullet shows its short key.
  • The branch hint becomes paca/<PROJ>-<REPO>-<N>-<topic>.
• list_repositories exposes short_key.
• The change_request_open description mentions PACA-12 and PACA-UI-12.
• Optional: CreateTaskBranch derives a default branch name from the key when none is given.

5. Web

• Project Settings → Git → Repositories:
  • A required, pre-filled "Short key" field in the link form.
  • A key badge with inline edit on each row.
• Task detail shows the key next to the repository path.
• Strings are added in all 9 locales.

6. Docs

• docs/ai-agent/git-agent-workflow.md: task-key linking, schema.
• One line in docs/plugins/git-provider-spi.md: providers never see task keys.

7. Related: connections per repository

With multi-repo projects, GitLab users will often add one project access token per repository, or a group token. Recognizing each token's type and reach (and not binding a public repo to a token that can't write to it) is provider work, tracked in Paca-AI/paca-plugin-gitlab#2. It is independent of short keys: each repo has its own key whatever connection serves it.

Migration / upgrade path

There are three separate layers:

1. Core schema. 000073_add_git_integration (git_repositories) is not in any release yet: v0.19.2 stops at 000072.
   • If this lands before v0.20 ships, the column can go straight into 000073, the same way feat(git): enhance project connection management #648 edits it in place. No backfill is needed.
   • Otherwise, a new migration backfills every existing link in SQL:
     • derive the key from the last path segment (uppercase, strip non-alphanumerics, truncate);
     • de-duplicate per project with row_number(), adding a numeric suffix;
     • avoid the project prefix;
     • then add NOT NULL and the unique index.
2. Existing branch names and links. Stored git_task_branches and git_task_links rows are untouched. PROJ-N keeps matching, so no existing branch or CR stops working.
   • Note for users coming from the community GitLab plugin v0.5.x: it also auto-linked feat/TRIM/200-x and number-only feat/200-x branches. Core never did, so those forms are not carried over.
3. Plugin data from the previous releases. Per-project tokens, linked repos and task↔MR/branch links lived in the plugin's own tables.
   • The new GitLab provider's 0002 drops them, and the plugin id change (com.gorlix.gitlab → com.paca.gitlab) means its migrations run in a fresh schema anyway. Today an upgrading user loses their connection, repositories and task links and must relink by hand.
   • feat(git): enhance project connection management #648 says the GitHub plugin will migrate the previous release's per-project tokens, repositories and PR/branch links into project-scoped token connections. GitLab should get the same path.
   • What I'd need to know: how a plugin migration can create core git_identities / git_repositories / git_task_* rows, and whether it can read the old plugin schema.
   • Once the new repos exist, the short keys come from layer 1.

Optional follow-up: plugin-sdk-go (additive, stays gitprovider.v1)

Everything above is core-only. An SDK change is needed only if we also want to link from change-request descriptions and commit messages, which the SPI doesn't carry today:

• SDK:
  • Add EventSubject.Title/Body (omitempty).
  • Add PushInfo.Commits []CommitInfo{SHA, Message}.
  • Update the golden wire shapes, the fake provider and the conformance fixtures.
• Core:
  • Run sync-git-spi.sh.
  • Scan the body in trackChangeRequest.
  • Handle EventPush at ingest, linking only and never triggering agents.
• Providers: fill these fields. For GitLab: object_attributes.description and commits[].message.

I'd rather keep the key grammar in core than have providers emit extracted task_refs. Otherwise every plugin has to reimplement the same parser.

Open questions

1. When PROJ-REPO-N names another repo of the project: ignore it (my proposal) or link anyway?
2. Should the SDK follow-up go in the same PR or a separate one?
3. Should this wait for feat(git): enhance project connection management #648 to merge, or be based on its branch? And can the column still be folded into 000073 before v0.20?
4. Plugin data migration: what mechanism will the GitHub plugin use to move legacy per-project tokens, repos and links into core? I'd like to do the same for GitLab, including reading from the old com.gorlix.gitlab schema.

Testing plan

• Parser unit tests: TRIM-UI-200, feat/TRIM-UI-200-x, TRIM-200, and fix TRIM-UI-200 and TRIM-7. None of them may yield UI-200.
• Service tests: right repo vs. wrong repo, and legacy PROJ-N.
• Postgres tests: uniqueness of short_key per project, and the backfill migration (duplicates, prefix collision).
• Web tests: GitSettings and locale parity.
• e2e: git-settings.
• Manual:
  1. Project TRIM with two GitLab repos keyed UI and API.
  2. A change request on feat/TRIM-UI-200-x in the UI repo links task 200.
  3. The same branch in the API repo links nothing.