specguard-mcp 0.1.4 → 0.1.5

package/README.md

@@ -34,7 +34,7 @@ refuses to boot and takes the tools that needed no configuration down with it.
 | --- | --- | --- | --- |
 | `SPECGUARD_ENDPOINT` | `get_repository_overview`, `list_repositories`, `add_repository`, `registrable_repositories` | — | your SpecGuard instance's root URL, **including the scheme** — e.g. `https://specguard.example.com`, or `http://localhost:3000`. A value with no scheme is refused by name (`SPECGUARD_ENDPOINT is not a usable URL: "sg.example.com"`) rather than surfacing later as an opaque failure. `SPECGUARD_URL` is accepted as an alias, and is the name every message uses when it is the one you set. A blank value counts as unset, so leaving `SPECGUARD_ENDPOINT` empty in a templated config falls through to `SPECGUARD_URL` instead of suppressing it |
 | `SPECGUARD_API_KEY` | `get_repository_overview` | — | an agent/CI API key (`sgk_…`) issued by that deployment |
-| `SPECGUARD_USER_API_KEY` | `list_repositories`, `add_repository`, `registrable_repositories`, `remove_repository`, `create_repository_api_key`, `revoke_repository_api_key` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
+| `SPECGUARD_USER_API_KEY` | `list_repositories`, `add_repository`, `registrable_repositories`, `remove_repository`, `create_repository_api_key`, `revoke_repository_api_key`, `list_repository_members`, `add_repository_member`, `update_repository_member_permissions`, `remove_repository_member`, `rename_repository` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
 | `SPECGUARD_LINT_COMMAND` | `lint_intent_annotations` | `specguard-lint` | the command that runs the linter. Most Ruby projects need `bundle exec specguard-lint` |
 | `SPECGUARD_TIMEOUT_MS` | HTTP tools | `30000` | how long a call to SpecGuard may take |
 
@@ -434,6 +434,47 @@ speaks for.
 It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
 `add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
 
+### `near_duplicate_clusters`
+
+Runs SpecGuard's near-duplicate census over a repository's tests — which tests *read alike* (same
+body text, whatever file they sit in), clustered by similarity. Answers the refactoring question
+the overview's per-run rankings cannot: where the same test is written twice, before you delete or
+merge anything.
+
+**This is the expensive read in this toolset.** The census is linear but measured in seconds —
+seven queries at every size, tens of seconds extrapolated at the 20,000-test design point — which
+is why the platform serves it only to a client that asks (`?near_duplicates=`, shipped by SPGD-703)
+and answers `near_duplicates: null` on the plain overview. Calling this tool **is** the ask;
+`get_repository_overview` never sends it, so an agent reading the overview cannot pay the census by
+accident.
+
+**This tool takes no arguments** — nothing about the census is choosable. The clusters are the
+repository's, computed over every run; one call returns them all. (The server reads only that the
+`near_duplicates` key is *present* — `=false` would open it too — so there is no value for an
+argument to carry.)
+
+Read the response with its own rules in mind:
+
+- `similarity_floor` and `similarity_basis` sit **first** in the block and qualify every figure
+  below them — a cluster count without what "similar" meant is a count you cannot act on.
+- `member_count` (texts in the repository, across every run) and `example_count` (examples in the
+  one run `weighed_run_id` names) are **different grains**: a three-example table-driven loop is
+  one member and three examples. Never fold them.
+- `truncated: true` means the `clusters` list was cut at the cap while the counts above it
+  (`cluster_count`, `identity_count`, `clustered_*`) describe the whole census.
+- `unobserved_members: true` on a cluster says a member identity the weighed run did not observe
+  (deleted, renamed, deselected) is still listed — do not reconcile the member list against that
+  run's examples.
+- `similarity_range` is `[strongest, weakest]`: membership is transitive, similarity is not.
+- `total_seconds` is `null` where nothing was timed — never a zero that would read as free.
+- `clusters: []` with a real `identity_count` is the **success** state (nothing reads alike); the
+  three silences — nothing ingested, nothing embedded, nothing alike — are kept distinguishable by
+  `recorded_count` / `identity_count` / the list itself.
+
+Same credential and endpoint as `get_repository_overview` (`sgk_…` repository key on
+`GET /api/v1/repository`); the response is that endpoint's full body with the `near_duplicates`
+block opened, passed through unmodified.
+
 ### `remove_repository`
 
 Removes a repository from SpecGuard — and with it **every key, run and intent on it**. This is the
@@ -498,6 +539,114 @@ means the key is revoked.
 It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
 `add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
 
+### `list_repository_members`
+
+Lists who has access to a SpecGuard repository: one row per member with their `handle`,
+`permissions`, `granted_by` (who last set them) and `created_at`, ordered by handle.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+
+The list answers **memberships only** and never reports how many CI keys a member has minted
+(`keys_minted`) — that is a separate `keys.manage` disclosure this endpoint deliberately withholds;
+the API-keys tools are the surface for it. The response carries **no membership id**, by design.
+
+Authorization is the `members.manage` capability: a caller who is not a member is refused `404`
+(the repository's existence stays hidden), and a member without `members.manage` is refused `403`
+with SpecGuard's own sentence, verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `add_repository_member`
+
+Grants a person access to a SpecGuard repository by their GitHub handle, with an optional list of
+permissions.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository to grant access to — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `handle` | the person's GitHub **login** — `octocat`, not a profile URL and not a display name; SpecGuard refuses both with its own sentence |
+| `permissions` | an optional list of permission strings (`view`, `keys.manage`, `members.manage`, `repo.delete`); omit it to grant access with no additional permissions |
+
+Each resolution failure — nobody has signed in as that handle yet, the account is archived, the
+handle is ambiguous, the handle is not a login — arrives as a **distinguishable** 400 message
+naming the exact next move. The grantor recorded on the membership is always the person behind
+`SPECGUARD_USER_API_KEY`; no argument can name a different one.
+
+On success (`201`) the response carries a `member` block (`handle`, `permissions`, `granted_by`,
+`created_at`) — and **no membership id**, by design. Authorization is the `members.manage`
+capability; a member without it is refused `403` with SpecGuard's own sentence, verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `update_repository_member_permissions`
+
+Replaces one member's permission set on a SpecGuard repository.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository the membership belongs to — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `member_id` | the id of the **membership** row to edit — not a user id, not the handle. Scoped to `repository_id`: a foreign membership id is refused `404` |
+| `permissions` | the member's **complete new** permission set (`view`, `keys.manage`, `members.manage`, `repo.delete`) — it replaces what they hold today, it is not merged |
+
+**`permissions` replaces the whole set** — name every permission the member should end with.
+Values are validated by SpecGuard; an unknown value is refused with its own sentence, verbatim.
+
+**Known limitation:** no API endpoint serves the membership id — the member list and the
+add-member response both omit it by design — so the id must be obtained from the platform (today
+via the repository's web members page). There is no name-based lookup. Authorization is the
+`members.manage` capability; a member without it is refused `403` with SpecGuard's own sentence,
+verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `remove_repository_member`
+
+Revokes one person's access to a SpecGuard repository by removing their membership. A `204` means
+it is revoked.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository the membership belongs to — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `member_id` | the id of the **membership** row to revoke — not a user id, not the handle. Scoped to `repository_id`: a foreign membership id is refused `404` |
+
+**Revoking does NOT revoke that member's minted CI keys.** Any `sgk_…` keys they created on the
+repository keep authenticating by design; the lever for those is the API-keys surface
+(`revoke_repository_api_key`), not this one. Self-revocation is permitted — after it, the caller's
+next request to the member routes answers `404`, not `403`. The repository owner's membership
+cannot be removed at all. The same known limitation as the edit tool applies to `member_id`: no
+endpoint serves it, so it comes from the platform's web members page today. Authorization is the
+`members.manage` capability; a member without it is refused `403` with SpecGuard's own sentence,
+verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `rename_repository`
+
+Renames a SpecGuard repository — changes the `org/repo` GitHub full name it is registered under —
+keeping every API key, run and intent on it.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the id of the repository to rename — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `github_full_name` | the new GitHub full name, `org/repo` — sent top-level in the body, not nested under `repository` |
+
+This is the alternative to the remove-and-re-register path: that one **deletes every API key, run
+and intent** on the repository (`remove_repository`), while this keeps all of them. **Authorization
+is owner-only** — deliberately narrower than removal: a member granted `repo.delete` may destroy
+the repository but may not rename it. The owner check also redeems a browser-issued grant valid for
+7 days; a nil or stale one is refused `403` with SpecGuard's own sentence naming the fix
+(re-grant via the browser). A name another repository already holds is refused `400` — `taken`, not
+`409` — verbatim. The `200` body is `{repository: …}` in the same shape `list_repositories` serves.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
 ## How it works
 
 ```

package/dist/src/support/specguard-api.d.ts

@@ -25,6 +25,18 @@ export declare function getJson(api: ApiConfig, path: string, query: Record<stri
  * send a body whose `Content-Type` says JSON and whose bytes are not.
  */
 export declare function postJson(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<unknown>;
+/**
+ * `PATCH` with a JSON body — the mutating-without-replacing half of the
+ * transport, and deliberately the SAME function underneath `postJson`, for the
+ * reason that header states: everything expensive about this module is about
+ * the deadline, not the verb.
+ *
+ * Routed through `requestJson` rather than `deleteJson`'s raw-body handling,
+ * because every PATCH this surface serves answers `200` WITH a JSON body —
+ * `requestJson`'s parse is correct here, and re-deriving success handling would
+ * be a third copy of the one status check.
+ */
+export declare function patchJson(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<unknown>;
 /**
  * `DELETE` — the destructive half of the transport, and deliberately the SAME
  * function underneath `postJson` rather than beside it, for the reason
@@ -58,6 +70,13 @@ export declare function deleteJson(api: ApiConfig, path: string, fetchImpl: type
  * answers with an array.
  */
 export declare function postJsonObject(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<Record<string, unknown>>;
+/**
+ * `patchJson`, narrowed exactly as `postJsonObject` narrows `postJson` — same
+ * guard, same sentence, same reason: `ToolResult.structured` is a
+ * `Record<string, unknown>`, so no tool should re-type the three-clause check
+ * on this verb either.
+ */
+export declare function patchJsonObject(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<Record<string, unknown>>;
 /**
  * `getJson`, narrowed to the object every tool here actually asks it for.
  *

package/dist/src/support/specguard-api.js

@@ -38,6 +38,23 @@ export async function postJson(api, path, body, fetchImpl) {
         body: JSON.stringify(body),
     });
 }
+/**
+ * `PATCH` with a JSON body — the mutating-without-replacing half of the
+ * transport, and deliberately the SAME function underneath `postJson`, for the
+ * reason that header states: everything expensive about this module is about
+ * the deadline, not the verb.
+ *
+ * Routed through `requestJson` rather than `deleteJson`'s raw-body handling,
+ * because every PATCH this surface serves answers `200` WITH a JSON body —
+ * `requestJson`'s parse is correct here, and re-deriving success handling would
+ * be a third copy of the one status check.
+ */
+export async function patchJson(api, path, body, fetchImpl) {
+    return requestJson(new URL(`${api.endpoint}${path}`), api, fetchImpl, {
+        method: "PATCH",
+        body: JSON.stringify(body),
+    });
+}
 /**
  * `DELETE` — the destructive half of the transport, and deliberately the SAME
  * function underneath `postJson` rather than beside it, for the reason
@@ -78,6 +95,15 @@ export async function deleteJson(api, path, fetchImpl) {
 export async function postJsonObject(api, path, body, fetchImpl) {
     return asJsonObject(await postJson(api, path, body, fetchImpl));
 }
+/**
+ * `patchJson`, narrowed exactly as `postJsonObject` narrows `postJson` — same
+ * guard, same sentence, same reason: `ToolResult.structured` is a
+ * `Record<string, unknown>`, so no tool should re-type the three-clause check
+ * on this verb either.
+ */
+export async function patchJsonObject(api, path, body, fetchImpl) {
+    return asJsonObject(await patchJson(api, path, body, fetchImpl));
+}
 /**
  * Everything both verbs do with a response, in one place.
  *

package/dist/src/support/specguard-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"specguard-api.js","sourceRoot":"","sources":["../../../src/support/specguard-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"specguard-api.js","sourceRoot":"","sources":["../../../src/support/specguard-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAkB,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,GAAc,EACd,IAAY,EACZ,KAAyC,EACzC,SAAkC;IAElC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC,CAAC;IAC9C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,GAAc,EACd,IAAY,EACZ,IAA6B,EAC7B,SAAkC;IAElC,OAAO,WAAW,CAAC,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE;QACpE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAc,EACd,IAAY,EACZ,IAA6B,EAC7B,SAAkC;IAElC,OAAO,WAAW,CAAC,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE;QACpE,MAAM,EAAE,OAAO;QACf,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAc,EACd,IAAY,EACZ,SAAkC;IAElC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,MAAM,gBAAgB,CAC/C,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC,EACjC,GAAG,EACH,SAAS,EACT,EAAE,MAAM,EAAE,QAAQ,EAAE,CACrB,CAAC;IAEF,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAEpE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAc,EACd,IAAY,EACZ,IAA6B,EAC7B,SAAkC;IAElC,OAAO,YAAY,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAc,EACd,IAAY,EACZ,IAA6B,EAC7B,SAAkC;IAElC,OAAO,YAAY,CAAC,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,WAAW,CACxB,GAAQ,EACR,GAAc,EACd,SAAkC,EAClC,OAAoB;IAEpB,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAEhF,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAEpE,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,GAAG,GAAG,CAAC,QAAQ,aAAa,QAAQ,CAAC,MAAM,8BAA8B;YACvE,cAAc,GAAG,CAAC,gBAAgB,0DAA0D;YAC5F,gBAAgB,EAClB,QAAQ,CAAC,MAAM,CAChB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,SAAS,YAAY,CAAC,IAAa;IACjC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,QAAQ,CAAC,yDAAyD,CAAC,CAAC;IAChF,CAAC;IAED,OAAO,IAA+B,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAc,EACd,IAAY,EACZ,KAAyC,EACzC,SAAkC;IAElC,OAAO,YAAY,CAAC,MAAM,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;AAClE,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,SAAS,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;AAgBnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,KAAK,UAAU,gBAAgB,CAC7B,GAAQ,EACR,GAAc,EACd,SAAkC,EAClC,OAAoB;IAEpB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,KAAgD,CAAC;IAErD,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAmB,CAAC,OAAO,EAAE,EAAE;QACzD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,OAAO,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACzB,6EAA6E;QAC7E,6EAA6E;QAC7E,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAClC,SAAS,CAAC,GAAG,EAAE;gBACb,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE;oBACrC,MAAM,EAAE,kBAAkB;oBAC1B,YAAY,EAAE,eAAe;oBAC7B,sEAAsE;oBACtE,sEAAsE;oBACtE,gEAAgE;oBAChE,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;iBAC9E;gBACD,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;gBAC7D,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;YACF,QAAQ;SACT,CAAC,CAAC;QACH,IAAI,QAAQ,KAAK,SAAS;YAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QAEhD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC7D,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QAE5C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6EAA6E;QAC7E,0EAA0E;QAC1E,4EAA4E;QAC5E,6EAA6E;QAC7E,IAAI,KAAK,YAAY,QAAQ;YAAE,MAAM,KAAK,CAAC;QAE3C,0EAA0E;QAC1E,0EAA0E;QAC1E,6EAA6E;QAC7E,uEAAuE;QACvE,8DAA8D;QAC9D,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QAEnD,MAAM,IAAI,QAAQ,CAChB,mBAAmB,GAAG,CAAC,QAAQ,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI;YAC5F,SAAS,GAAG,CAAC,gBAAgB,0DAA0D,CAC1F,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,uEAAuE;QACvE,wEAAwE;QACxE,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,QAAQ,CAAC,GAAc;IAC9B,OAAO,IAAI,QAAQ,CAAC,GAAG,GAAG,CAAC,QAAQ,2BAA2B,GAAG,CAAC,gBAAgB,KAAK,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,eAAe,CAAC,MAAc,EAAE,IAAY,EAAE,GAAc;IACnE,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,UAAU,CAAC;QAEvD,OAAO,IAAI,QAAQ,CACjB,yCAAyC,QAAQ,eAAe,MAAM,kBAAkB;YACtF,GAAG,GAAG,CAAC,QAAQ,IAAI,SAAS,GAAG,EACjC,MAAM,CACP,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,IAAI,QAAQ,CACjB,GAAG,GAAG,CAAC,QAAQ,2CAA2C,GAAG,CAAC,gBAAgB,UAAU;YACtF,wCAAwC,EAC1C,MAAM,CACP,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,IAAI,QAAQ,CACjB,sBAAsB,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,EAC3F,MAAM,CACP,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,MAAc;IAClD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7F,MAAM,OAAO,GAAI,MAAkC,CAAC,SAAS,CAAC,CAAC;IAC/D,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAE3E,OAAO,kCAAkC,MAAM,MAAM,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;AACxE,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/src/tools/add-repository-member.d.ts

@@ -0,0 +1,31 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `POST /api/v1/repositories/:repository_id/members` as a tool — shipped in the
+ * platform (`specguard/config/routes.rb`,
+ * `Api::V1::UserRepositoryMembersController#create`, SPGD-875).
+ *
+ * == The handle is the LOGIN itself
+ *
+ * `User.resolve_by_handle` refuses a profile URL and a display name with its
+ * own sentence ("Send the login itself — octocat, not a profile URL or a
+ * display name"), and each non-`:found` resolution — never-signed-in,
+ * archived, ambiguous, malformed — arrives as a distinguishable 400 sentence
+ * through the landed `refusalMessage` branch. This bridge does not re-derive
+ * that vocabulary: a client-side copy is a rule with no owner, free to drift
+ * from the one that actually decides.
+ *
+ * == The grantor is always the authenticated principal
+ *
+ * `granted_by_user` is stamped server-side from the `sgu_` credential and is
+ * deliberately absent from the permitted params. The tool therefore takes no
+ * grantor argument, and no caller can name one.
+ *
+ * == The 201 body omits the membership id, by server design
+ *
+ * `#serialize` serves `handle`, `permissions`, `granted_by`, `created_at` —
+ * and no id, because ids are not portable between repositories and serving
+ * one invites treating it as portable. See
+ * `update_repository_member_permissions` for where the id comes from today.
+ */
+declare const addRepositoryMember: ToolDefinition;
+export default addRepositoryMember;

package/dist/src/tools/add-repository-member.js

@@ -0,0 +1,105 @@
+import { postJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+import { optionalStringArray, requireString } from "./args.js";
+/**
+ * `POST /api/v1/repositories/:repository_id/members` as a tool — shipped in the
+ * platform (`specguard/config/routes.rb`,
+ * `Api::V1::UserRepositoryMembersController#create`, SPGD-875).
+ *
+ * == The handle is the LOGIN itself
+ *
+ * `User.resolve_by_handle` refuses a profile URL and a display name with its
+ * own sentence ("Send the login itself — octocat, not a profile URL or a
+ * display name"), and each non-`:found` resolution — never-signed-in,
+ * archived, ambiguous, malformed — arrives as a distinguishable 400 sentence
+ * through the landed `refusalMessage` branch. This bridge does not re-derive
+ * that vocabulary: a client-side copy is a rule with no owner, free to drift
+ * from the one that actually decides.
+ *
+ * == The grantor is always the authenticated principal
+ *
+ * `granted_by_user` is stamped server-side from the `sgu_` credential and is
+ * deliberately absent from the permitted params. The tool therefore takes no
+ * grantor argument, and no caller can name one.
+ *
+ * == The 201 body omits the membership id, by server design
+ *
+ * `#serialize` serves `handle`, `permissions`, `granted_by`, `created_at` —
+ * and no id, because ids are not portable between repositories and serving
+ * one invites treating it as portable. See
+ * `update_repository_member_permissions` for where the id comes from today.
+ */
+const addRepositoryMember = {
+    name: "add_repository_member",
+    title: "Add repository member",
+    description: "Grants a person access to a SpecGuard repository by their GitHub handle, with an optional " +
+        "list of permissions. " +
+        "The `handle` is the LOGIN itself — `octocat`, not a profile URL and not a display name: " +
+        "SpecGuard refuses each of those with its own sentence, and every other resolution failure " +
+        "(nobody has signed in as that handle yet, the account is archived, the handle is ambiguous) " +
+        "arrives as a distinguishable 400 message naming the exact next move. " +
+        "The grantor recorded on the membership is always the person behind this server's user API " +
+        "key — the server stamps it, and no argument can name a different one. " +
+        "On success (201) the response carries a `member` block (`handle`, `permissions`, " +
+        "`granted_by`, `created_at`). It carries NO membership id, by design: ids are not portable " +
+        "between repositories, and editing or revoking a membership names a membership id obtained " +
+        "from the platform (today only via the web members page) — see the edit/revoke tools. " +
+        "Permissions are strings from SpecGuard's own set (`view`, `keys.manage`, `members.manage`, " +
+        "`repo.delete`); an unknown value is refused in SpecGuard's own words, and omitting the " +
+        "list grants access with no additional permissions. The repository owner cannot be added " +
+        "(they hold everything by construction). " +
+        "Authorization is the `members.manage` capability — a member without it is refused 403 in " +
+        "SpecGuard's own words. " +
+        "Takes `repository_id` — the numeric id `list_repositories` reports, not the `org/repo` " +
+        "handle. " +
+        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), the same credential `add_repository` " +
+        "writes with and a DIFFERENT one from the sgk_… repository key `get_repository_overview` uses.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repository_id: {
+                type: "string",
+                description: "The repository to grant access to — its numeric id, as `add_repository` " +
+                    "returns and `list_repositories` reports, not the `org/repo` handle.",
+            },
+            handle: {
+                type: "string",
+                description: "The GitHub login of the person to add, e.g. `octocat` — not a profile URL and not a " +
+                    "display name; SpecGuard refuses both with its own sentence. The person must have " +
+                    "signed in to SpecGuard at least once.",
+            },
+            permissions: {
+                type: "array",
+                items: { type: "string" },
+                description: "An optional list of permission strings from SpecGuard's own set (`view`, " +
+                    "`keys.manage`, `members.manage`, `repo.delete`). Omit it to grant access with no " +
+                    "additional permissions. SpecGuard validates the values and refuses an unknown one " +
+                    "in its own words.",
+            },
+        },
+        required: ["repository_id", "handle"],
+        // Closed for the reason every tool here states — and on a WRITE, a silently
+        // dropped misspelled argument still grants something, just not what the
+        // agent believed it was asking for.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        const repositoryId = requireString(args["repository_id"], "repository_id");
+        const handle = requireString(args["handle"], "handle");
+        const permissions = optionalStringArray(args["permissions"], "permissions");
+        const api = requireUserApiConfig(context.config);
+        // Top-level `{handle, permissions}` — the shape the controller permits,
+        // matching `add_repository`'s stated rule: this is JSON an agent writes,
+        // not a Rails form. `permissions` omitted when absent so the server's own
+        // default applies; passed through as an ARRAY when present (the column is
+        // `text[]`, and a scalar on the wire is silently dropped server-side).
+        const created = await postJsonObject(api, `/api/v1/repositories/${encodeURIComponent(repositoryId)}/members`, permissions === undefined ? { handle } : { handle, permissions }, context.fetch);
+        // Unreshaped, the standing rule — and the 201 body is the only answer this
+        // verb gives; nothing here exists to re-fetch elsewhere.
+        return {
+            text: JSON.stringify(created, null, 2),
+            structured: created,
+        };
+    },
+};
+export default addRepositoryMember;
+//# sourceMappingURL=add-repository-member.js.map

package/dist/src/tools/add-repository-member.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-repository-member.js","sourceRoot":"","sources":["../../../src/tools/add-repository-member.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,mBAAmB,GAAmB;IAC1C,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,uBAAuB;IAC9B,WAAW,EACT,4FAA4F;QAC5F,uBAAuB;QACvB,0FAA0F;QAC1F,4FAA4F;QAC5F,8FAA8F;QAC9F,uEAAuE;QACvE,4FAA4F;QAC5F,wEAAwE;QACxE,mFAAmF;QACnF,4FAA4F;QAC5F,4FAA4F;QAC5F,uFAAuF;QACvF,6FAA6F;QAC7F,yFAAyF;QACzF,0FAA0F;QAC1F,0CAA0C;QAC1C,2FAA2F;QAC3F,yBAAyB;QACzB,yFAAyF;QACzF,UAAU;QACV,oFAAoF;QACpF,+FAA+F;IACjG,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,0EAA0E;oBAC1E,qEAAqE;aACxE;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,sFAAsF;oBACtF,mFAAmF;oBACnF,uCAAuC;aAC1C;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EACT,2EAA2E;oBAC3E,mFAAmF;oBACnF,oFAAoF;oBACpF,mBAAmB;aACtB;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,EAAE,QAAQ,CAAC;QACrC,4EAA4E;QAC5E,wEAAwE;QACxE,oCAAoC;QACpC,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC,CAAC;QAC3E,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;QACvD,MAAM,WAAW,GAAG,mBAAmB,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC;QAE5E,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,wEAAwE;QACxE,yEAAyE;QACzE,0EAA0E;QAC1E,0EAA0E;QAC1E,uEAAuE;QACvE,MAAM,OAAO,GAAG,MAAM,cAAc,CAClC,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,UAAU,EAClE,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAChE,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,2EAA2E;QAC3E,yDAAyD;QACzD,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,mBAAmB,CAAC"}

package/dist/src/tools/args.d.ts

@@ -66,3 +66,29 @@ export declare function optionalString(value: unknown, field: string): string |
  */
 export declare function requireString(value: unknown, field: string): string;
 export declare function optionalBoolean(value: unknown, field: string): boolean | undefined;
+/**
+ * An optional array of non-blank strings, or nothing.
+ *
+ * The SHAPE-ONLY sibling of the linter's `optionalStringArray` (which stays in
+ * `lint-intent-annotations.ts` because its refusals — empty list, leading dash
+ * — are about the linter's own argument grammar and throw `CommandError`). This
+ * one answers only "is it an array of strings" and always throws
+ * `ArgumentError`, which is what a pass-through array of permission names
+ * needs: the platform is the authority on which strings are legal, and a
+ * client-side copy of that rule is a rule with no owner, free to drift from the
+ * one that actually decides.
+ */
+export declare function optionalStringArray(value: unknown, field: string): string[] | undefined;
+/**
+ * A mandatory array of non-blank strings, and nothing else will do.
+ *
+ * The mandatory counterpart of `optionalStringArray`, added with
+ * `update_repository_member_permissions` (SPGD-885): the server column behind
+ * that call is `text[]`, and a scalar on the wire is silently dropped
+ * server-side — so the array shape is checked HERE, before a write, rather
+ * than persisted as a member holding nothing. Blank entries are dropped rather
+ * than refused: the server's own normalisation does the same, so refusing here
+ * would be a second vocabulary the caller must satisfy before the one that
+ * decides even sees the request.
+ */
+export declare function requireStringArray(value: unknown, field: string): string[];

package/dist/src/tools/args.js

@@ -93,4 +93,56 @@ export function optionalBoolean(value, field) {
         throw new ArgumentError(`\`${field}\` must be a boolean.`);
     return value;
 }
+/**
+ * An optional array of non-blank strings, or nothing.
+ *
+ * The SHAPE-ONLY sibling of the linter's `optionalStringArray` (which stays in
+ * `lint-intent-annotations.ts` because its refusals — empty list, leading dash
+ * — are about the linter's own argument grammar and throw `CommandError`). This
+ * one answers only "is it an array of strings" and always throws
+ * `ArgumentError`, which is what a pass-through array of permission names
+ * needs: the platform is the authority on which strings are legal, and a
+ * client-side copy of that rule is a rule with no owner, free to drift from the
+ * one that actually decides.
+ */
+export function optionalStringArray(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new ArgumentError(`\`${field}\` must be an array of strings.`);
+    const entries = value.map((entry) => {
+        if (typeof entry !== "string")
+            throw new ArgumentError(`\`${field}\` must contain only strings.`);
+        // Trimmed like its scalar siblings: a value an agent produced by
+        // concatenating strings arrives with whitespace that is not part of what it
+        // meant to send.
+        return entry.trim();
+    });
+    return entries;
+}
+/**
+ * A mandatory array of non-blank strings, and nothing else will do.
+ *
+ * The mandatory counterpart of `optionalStringArray`, added with
+ * `update_repository_member_permissions` (SPGD-885): the server column behind
+ * that call is `text[]`, and a scalar on the wire is silently dropped
+ * server-side — so the array shape is checked HERE, before a write, rather
+ * than persisted as a member holding nothing. Blank entries are dropped rather
+ * than refused: the server's own normalisation does the same, so refusing here
+ * would be a second vocabulary the caller must satisfy before the one that
+ * decides even sees the request.
+ */
+export function requireStringArray(value, field) {
+    if (value === undefined || value === null) {
+        throw new ArgumentError(`\`${field}\` is required.`);
+    }
+    if (!Array.isArray(value))
+        throw new ArgumentError(`\`${field}\` must be an array of strings.`);
+    const entries = value.map((entry) => {
+        if (typeof entry !== "string")
+            throw new ArgumentError(`\`${field}\` must contain only strings.`);
+        return entry.trim();
+    });
+    return entries.filter((entry) => entry !== "");
+}
 //# sourceMappingURL=args.js.map

package/dist/src/tools/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/tools/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,KAAa;IAC1D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,sBAAsB,CAAC,CAAC;IACzF,8EAA8E;IAC9E,gFAAgF;IAChF,2EAA2E;IAC3E,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc,EAAE,KAAa;IACzD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,iBAAiB,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,sBAAsB,CAAC,CAAC;IAEzF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,uBAAuB,CAAC,CAAC;IAE/E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,KAAa;IAC3D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,uBAAuB,CAAC,CAAC;IAC3F,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/tools/args.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/index.d.ts

@@ -34,12 +34,21 @@ import type { ToolDefinition } from "./types.js";
  *
  * == What is deliberately absent
  *
- * `/check-intent` and duplicate clustering are NOT here and must not be added
- * until their backing engine and data exist (SPGD-114 / SPGD-115). A tool
- * advertised in `tools/list` is a promise an agent will act on: wrapping an
- * endpoint that does not exist would produce a server that discovers cleanly
- * and fails on use, which is worse than not offering the tool, because the
- * agent has already committed to a plan by the time it finds out.
+ * `/check-intent` is NOT here and must not be added until its backing endpoint
+ * exists — `specguard/config/routes.rb:113` carries it as a comment only, which
+ * is the evidence this forbid rests on. A tool advertised in `tools/list` is a
+ * promise an agent will act on: wrapping an endpoint that does not exist would
+ * produce a server that discovers cleanly and fails on use, which is worse than
+ * not offering the tool, because the agent has already committed to a plan by
+ * the time it finds out.
+ *
+ * Duplicate clustering was once under this same forbid, on the same standing
+ * rule — no tool may wrap what has not shipped. That half retired when the
+ * platform moved: SPGD-703 (`specguard` `c43dc19`, 2026-08-28) shipped
+ * `GET /api/v1/repository?near_duplicates=`, serving
+ * `RepositoryOverview#serialized_near_duplicates` behind an opt-in ask, and
+ * `near_duplicate_clusters` below wraps it. What moved was the platform, not
+ * the bar.
  *
  * == The fourth: the first tool that WRITES
  *
@@ -99,9 +108,44 @@ import type { ToolDefinition } from "./types.js";
  * `requestJson`'s JSON parse.
  *
  * The standing rule itself is unchanged and still binding — which still keeps
- * out `/check-intent`, duplicate clustering, member management and rename: none
- * of their backing endpoints has shipped, and a tool advertised in `tools/list`
- * remains a promise an agent will act on.
+ * out `/check-intent`: it has no backing endpoint (`routes.rb:113` mounts it
+ * as a comment only). A tool advertised in `tools/list` remains a promise an
+ * agent will act on.
+ *
+ * == The ninth through twelfth: member management
+ *
+ *   - `list_repository_members`, `add_repository_member`,
+ *     `update_repository_member_permissions` and `remove_repository_member`
+ *     wrap the four `user_repository_members` endpoints (all shipped: SPGD-875,
+ *     specguard@origin/main).
+ *
+ * They also forced the transport's fourth verb: `update` is a PATCH, which
+ * arrived with `patchJson` in this same slice — 200 with a JSON body, so it
+ * routes through `requestJson` like `postJson` rather than `deleteJson`'s
+ * raw-body handling.
+ *
+ * A known limitation rides with them and is stated in the edit/revoke tool
+ * descriptions rather than papered over: PATCH and DELETE name a membership by
+ * id, but no endpoint serves that id (the platform's `#serialize` deliberately
+ * omits it), so the id comes from the platform's web members page today. That
+ * is a platform-side follow-up, not a client-side workaround — there is no
+ * name-based lookup.
+ *
+ * == The thirteenth: rename
+ *
+ *   - `rename_repository` wraps `PATCH /api/v1/repositories/:id` (shipped:
+ *     SPGD-878, `specguard@origin/main` e026793, PR #266).
+ *
+ * This is the entry the forbid above once named as "the natural next slice" —
+ * the platform moved (SPGD-878 shipped the endpoint), so the forbid retired
+ * exactly as the duplicate-clustering one did. It reuses `patchJson` landed
+ * with the member-management slice rather than minting a transport of its own.
+ * The verb's one asymmetry is carried in the tool description rather than
+ * papered over: rename authorizes OWNER-ONLY, while removal authorizes the
+ * BROADER `repo.delete` capability — a member who may destroy the repository
+ * may not rename it. Before this tool the bridge's only rename path was
+ * remove-and-re-register, which destroys every key, run and intent; this one
+ * keeps them.
  */
 export declare const TOOLS: readonly ToolDefinition[];
 export type { ToolContext, ToolDefinition, ToolResult } from "./types.js";