Skip to content

A channel's name is its slug, and a slug may carry underscores (#1038) - #1039

Merged
mkreyman merged 2 commits into
masterfrom
fix/channel-name-equals-slug
Nov 11, 2026
Merged

mkreyman merged 2 commits into
masterfrom
fix/channel-name-equals-slug

Conversation

@mkreyman

Copy link
Copy Markdown
Owner

Closes #1038.

A repo channel got its name from one rule and its slug from another, and the two drifted
on 17 of 29 projects. This makes the server the authority: a channel's slug and name are
both the repo basename, verbatim.

What changed

Server

  • Project slug format accepts _: /^[a-z0-9][a-z0-9_-]*[a-z0-9]$/.
  • A kind: :kb scope's name must equal its slug, on create and update. A name that is
    the same string up to case and separators (home_care_billing for slug
    home-care-billing, which MCP clients before 3.13 send) is stored as the slug, so an
    older client still gets a channel. A different string is refused with a 422 that names
    the slug. Work projects are not bound by it (see Defaults).
  • PATCH /api/v1/projects/:id takes slug for a kb scope. When the request carries no
    name, the name follows the slug. A name the caller sends is always judged, never
    overwritten. The audit entry now records slug in old/new state. A work project's slug
    change is a 422 (it used to be silently dropped). The existing unique index on
    (tenant_id, slug) covers archived projects, so a taken slug is still refused.
  • resolve_project (by slug) and the project_id reference resolver match on the FOLDED
    slug after an exact miss: lowercase, every non-alphanumeric run read as one -, on both
    sides. home-care-billing reaches home_care_billing and back. Like the other fuzzy
    identifiers, the fold resolves only a single ACTIVE match and otherwise falls through
    to repo_url/name. An exact slug still resolves an archived project.
  • OpenAPI: slug/name descriptions; update operation text.

MCP server (3.13.0)

  • handoff: deriveSlug keeps _; a created channel's name is always the slug; the
    name argument is gone (it could only produce a 422 now).
  • update_project sends slug.
  • create_kb_scope / create_project: name is "the same string as slug".

Testing

  • mix test on projects_test.exs, project_controller_test.exs,
    resolve_project_ref_test.exs, coordination_test.exs, intake_test.exs,
    channel_post_controller_test.exs, intake_source_controller_test.exs: 455 tests, 0
    failures before review; 458 after the review fixes. New: underscore slug accepted, kb name
    != slug refused (context + POST /kb-scopes), pre-3.13 client shape gets a channel named by
    its slug, kb slug rename with name following and audit, explicit name judged not
    overwritten, work slug change refused, taken slug (archived) refused, folded resolution
    both ways, exact wins over fold, ambiguous fold falls through, archived twin skipped, lone
    archived fold match not resolved, cross-tenant fold not resolved.
  • npm test in mcp-server/: 916 pass. New: underscore repo creates name == slug
    (ads_for_care), update_project sends slug.
  • mix credo --strict on changed lib files: clean.

Risk

  • Any client that PATCHes a work project with a slug in the body now gets 422 instead of a
    silent no-op. The MCP tool never sent it before this change.
  • A kb scope whose name is a different string from its slug can no longer be updated until
    both match. Every live one was aligned on 2026-11-11.
  • The folded lookup adds one query on an exact-slug miss; bounded by the tenant's project
    count.

How to revert

Revert the squash commit. No migration. Any channel already renamed to an underscore slug
keeps that slug; it stays resolvable by exact slug, and by repo_url.

Defaults you can overrule

  • name == slug is enforced for kb scopes only. Every live work project already complies,
    but enforcing it on work projects would be a larger change to fixtures and to
    create_project. Overrule in Project.validate_kb_name_equals_slug/1.
  • The folded slug lookup has no expiry; it is cheap and keeps old spellings working for
    sessions on an older client. Overrule in Projects.resolve_by_folded_slug/2.
  • Slug renames go through PATCH /projects/:id (orchestrator+, human-anchored tenant), not
    an agent-role kb-scope route.
  • A kb name that folds to its slug is stored as the slug instead of being refused, so
    pre-3.13 MCP clients keep working. Overrule in Project.validate_kb_name_equals_slug/1.

Review findings

  1. fixed high lib/loopctl/projects/project.ex:147 — MCP sessions on 3.12 or earlier still send the repo basename as the kb scope's name and the hyphenated form as its slug, which the server now refuses with 422; the folded lookup protects finding a channel but not creating one.
  2. fixed medium lib/loopctl/projects.ex:712 — pick_folded_match returns a project that is the fold's only match even when it is archived, so the new fuzzy slug pass can send resolve_project to a retired project.
  3. fixed low lib/loopctl/projects/project.ex:136 — name_follows_slug checks changed?(:name), so a name the caller sends explicitly is silently overwritten whenever it equals the stored name.
  4. fixed low mcp-server/index.js:4306 — The edited delete_project description still says 'nothing releases a slug', but update_project can now rename a kb scope, which frees its old slug.

A repo channel got its name from the raw repo basename and its slug from a
hyphen-only rule, so the two drifted on 17 of 29 projects. The server is now
the authority:

- Project slugs accept `_`, so a slug can be the repo basename verbatim.
- A kb scope's name must equal its slug (422 otherwise).
- PATCH /projects/:id takes `slug` for a kb scope (name follows, audited) and
  refuses it for a work project instead of dropping it.
- resolve_project and the project_id reference resolver match a slug on its
  folded form too, so `home-care-billing` and `home_care_billing` reach the
  same channel while channels are renamed.
- MCP 3.13.0: handoff keeps `_` in the derived slug and names the channel by
  it; update_project sends slug; tool descriptions say name == slug.
- A kb name that folds to its slug is stored as the slug instead of refused,
  so an MCP client before 3.13 (name home_care_billing, slug
  home-care-billing) still gets a channel. A different string is still 422.
- The folded slug lookup resolves only a single active project, like the
  other fuzzy identifiers; a lone archived match falls through.
- On PATCH the name follows the slug only when the request carries no name;
  a sent name is judged, never overwritten.
- delete_project's description says a kb rename frees the old slug.
- One fold function, Project.fold/1, shared by the changeset and lookups.
@mkreyman
mkreyman enabled auto-merge (squash) November 11, 2026 20:23
@mkreyman mkreyman closed this Nov 11, 2026
auto-merge was automatically disabled November 11, 2026 21:21

Pull request was closed

@mkreyman mkreyman reopened this Nov 11, 2026
@mkreyman
mkreyman enabled auto-merge (squash) November 11, 2026 21:21
@mkreyman
mkreyman merged commit c099ac2 into master Nov 11, 2026
17 checks passed
@mkreyman
mkreyman deleted the fix/channel-name-equals-slug branch November 11, 2026 21:26
mkreyman added a commit that referenced this pull request Nov 11, 2026
* A work project's slug can be renamed too (#1038)

#1039 let only a kind: kb scope's slug change and refused a work project's
with 422, so the four of the ten repo channels that are work projects could
not be aligned to their repo basename. Any project's slug can now change; the unique index still
refuses a taken one.

The name follows the slug only when the request carries no name and the
stored name equalled the stored slug, so a work project with a display name
keeps it. MCP 3.13.1 updates the update_project and handoff descriptions.

* Review fixes: a drifted kb scope still realigns on a slug-only rename

The name-follows clause matched only name == slug, which dropped the
unconditional follow a kb scope had, so a legacy kb row whose name drifted
from its slug got 422 on a slug-only rename. A kb scope's name follows again;
a work project's follows only when it was the slug. Also corrects the MCP
changelog (update_project and delete_project descriptions, not handoff) and
AC-5.1.6, which still said a slug cannot change.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Channel name must equal its slug (handoff tool and server)

1 participant