# Package Renames — Normalization Plan and Applied Waves

Task: #t2914. Thread: #agentteam-in-agentteam:0234da66.
Baseline for analysis: main @ dec57c87fc.

## Principles

1. Directory name equals package name (no `pkg mail` inside `dir runtime`).
2. One domain, one word across layers (api/service/store use the same domain name).
3. Layering lives in the path, not in a name prefix (`store/workflow/plan`, not `store/workflowplan`).
4. Overloaded words (`runtime`, `manage`, generic `api`) must be disambiguated.
5. Aliases use the shortest unambiguous package identity, such as
   `<domain>api` / `<domain>store`, only when a lexical collision requires one.
   The reviewed alias baseline (`guardrails/importalias/baseline.txt`) contains
   only `go/types`-validated shadowing or build-constraint exceptions.

## Applied in this branch (Waves 0–3)

| Wave | Applied commits |
|---|---|
| 0 | verified on `origin/main` at `a5659ebf14` |
| 1 | `f5629f6c33`, `b3815e16ea`, `49a2016d14` |
| 2 | `59f40f675f`, `dcd8f0d912`, `8e2f938a70` |
| 3a | `ad09f3fc38` |
| 3b | `99ce505885` |
| 3c | `e23c90bd22` |
| Cross-wave finalization and enforcement | `d603385ded` |

### Wave 0 — repository hygiene

- `tidb-slow.log` is ignored and no instances are tracked.
- Empty migration remnants do not contribute Go packages.
- `x/` is explicitly outside this normalization; it remains an independently
  owned vendored/nested-module tree.

### Wave 1 — token domain + name/dir alignment

| Old | New |
|---|---|
| `api/personal_access_tokens` (pkg `personal_access_tokens`) | `api/providertokens` |
| `service/personaltokens` | `service/providertokens` |
| `store/personalaccesstokens` | `store/providertokens` |
| `api/repository_access_tokens` | `api/repotokens` |
| `store/repositoryaccesstokens` | `store/repotokens` |
| `providers/mail/api` (pkg `mailapi`) | `providers/mail/mailapi` |
| `providers/mail/runtime` (pkg `mail`) | `providers/mail/mailruntime` |
| `providers/mail/store` (pkg `mail`) | `providers/mail/mailstore` |
| `coredb/testkit/runtime` (pkg `tidbruntime`) | `coredb/testkit/tidbruntime` |
| `api/meshx` (pkg `api`) | `api/meshxapi` |
| `service/agent` (pkg `agentruntime`) | `service/agentruntime` |
| `service/auth` (pkg `authflow`) | `service/authflow` |
| `service/extension` (pkg `extensionflow`) | `service/extensionflow` |
| `service/knowledgeqa/runtime` (pkg `knowledgeqa`) | `service/knowledgeqa/knowledgeqaruntime` |
| `service/maas` (pkg `hostedmodel`) | pkg `maas` |
| `service/message` (pkg `messaging`) | pkg `message` |
| `service/serviceaccount` (pkg `serviceaccountflow`) | pkg `serviceaccount` |
| `service/serviceevent` (pkg `serviceeventflow`) | pkg `serviceevent` |
| `service/workspace` (pkg `workspaceflow`) | pkg `workspace` |
| `store/extension` (pkg `extensionstore`) | pkg `extension` |

### Wave 2a — workflow grouping

| Old | New |
|---|---|
| `api/workflowrun` | `api/workflow/run` (pkg `run`) |
| `api/workflowplan` | `api/workflow/plan` |
| `api/workflowbinding` | `api/workflow/binding` |
| `api/workflowinvocation` | `api/workflow/invocation` |
| `store/workflowrun` | `store/workflow/run` |
| `store/workflowplan` | `store/workflow/plan` |
| `store/workflowbinding` | `store/workflow/binding` |
| `store/workflowinvocation` | `store/workflow/invocation` |
| `store/workflowcalendar` | `store/workflow/calendar` |

`api/workflowcalendar` does not exist on main (untracked local files only).

### Wave 2b — manage flattening

| Old | New |
|---|---|
| `workflow/plan/manage` | `workflow/planmanage` |
| `workflow/run/manage` | `workflow/runmanage` |
| `workflow/binding/manage` | `workflow/bindingmanage` |
| `workflow/invocation/manage` | `workflow/invocationmanage` |

`schedule/manage` unchanged (never collides; dir already equals package name).

### Wave 2c — runtime disambiguation

| Old | New |
|---|---|
| `workflow/runruntime` | `workflow/orchestrator` |
| `workflowerrorcontract` | `workflow/errcontract` |

### Wave 3a — shorter semantic domain names

| Old | New |
|---|---|
| `api/publicrepocache` | `api/repocache` |
| `service/publicrepocache` | `service/repocache` |
| `store/publicrepocache` | `store/repocache` |
| `api/automations` | `api/automation` |
| `store/automations` | `store/automation` |
| `service/agentmanagement` | `service/agentapproval` |
| `service/channelmanagement` | `service/channeladmin` |
| `store/channelmanagement` | `store/channeladmin` |
| `service/collaboratorrequest` | `service/collaborator` |
| `service/pullrequestwatch` | `service/prwatch` |
| `providers/feishucustombot` | `providers/feishubot` |
| `maas/hostedavailability` | `maas/availability` |
| `core/runtimecatalog` | `core/catalog` |
| `internal/runtime` | `internal/meshxruntime` |
| `extension/runtime` | `extension/runner` |
| `internal/unreadruntime` | `internal/unread` |
| `store/unreadruntime` | `store/unread` |

### Wave 3b — path-owned hierarchy

| Old | New |
|---|---|
| `service/appinstallation` | `service/app/installation` |
| `core/appcapabilities` | `core/app/capabilities` |
| `providers/mail/connectionconfig` | `providers/mail/connection` |
| `service/teamroleproposal` | `service/team/roleproposal` |
| `service/knowledgeqa/knowledgeqaruntime` | `service/knowledgeqa/runtime` |
| `internal/workspaceowner` | `internal/workspace/owner` |
| `internal/workspacerouter` | `internal/workspace/router` |
| `internal/trustedidentity` | `internal/identity/trusted` |
| `api/runtimeidentity` | `api/identity/lookup` |
| `service/resourceaccess` | `service/resource/access` |
| `service/resourceactivity` | `service/resource/activity` |
| `service/resourcerepos` | `service/resource/repos` |
| `store/resourceactivity` | `store/resource/activity` |
| `store/resourcememory` | `store/resource/memory` |
| `store/resourcerepos` | `store/resource/repos` |
| `store/resourceroles` | `store/resource/roles` |
| `store/resourceskills` | `store/resource/skills` |
| `service/rolemanagement` | `service/role/execution` |
| `store/rolemanagement` | `store/role/execution` |
| `service/roleagents` | `service/role/agents` |

### Wave 3c — content and Knowledge Q&A ownership

| Old | New |
|---|---|
| `api/contentstore` | `api/content` |
| `service/contentstore` | `service/content` |
| `store/contentstore` | `store/content` |
| `service/contentmigration` | `service/content/migration` |
| `store/contentmigration` | `store/content/migration` |
| `internal/contentstore` | `internal/contentpayload` |
| `internal/knowledgeqa` | `internal/knowledgeqa/protocol` |

### Enforcement

`guardrails/repository/check-go-package-names.py` scans tracked Go files outside
`x/` and enforces:

- lowercase ASCII package names without underscores;
- package name equals directory basename (`main` is the executable exception);
- package comments name the declared package;
- no retired full Go import strings remain in non-Go text.

`x/` and the repository-analysis fixture under
`kits/agentteam-insight/testdata/smoke/fixture-repo/` remain outside this policy.

## Explicit non-goals

- `core` vs `service` split, the manage/engine boundary, `serviceactor` vs
  `serviceaccount` (two products), `x/` vendored tree, `ags`/`agsbridge`
  (external system names) — verified deliberate, kept.