docs(guide): add fleet.task-permissions module (#23) #24

2026-07-16T14:45:17-04:00

hiveiq commented

2026-07-16 14:45:17 -04:00

Closes #23.

fleet.task-permissions returned 404 — the Task Permissions tab shipped in hiveops-fleet#119 and is live on bcos.dev with no guide coverage at all. fleet.tasks mentions permissions exactly once and never describes the grant model.

This is the setting that decides which commands a customer may push to their own ATMs. Deny-by-default, per-institution, per-command. Arguably the highest-consequence fleet setting we have, and it was the least documented.

The 5 tabs

Tab	Covers
Customer	Grant/revoke, saves instantly with no undo, why only Reboot + Restart Agent are offered
Internal	Triage for "customer cannot reboot", the two 403 messages and what each means, what we never widen, when to escalate
Architect	Deny-by-default rationale, the two independent gates, two layers of refusal, replace-not-merge, why `GRANTABLE` is code not config, audit limits
Testing	8 checks against bcos.dev incl. the 400-on-`CONFIG_UPDATE` case, with restore steps
Claude	Ownership, table, endpoint/role matrix, gotchas

Grounded in source

Every claim traced to hiveops-fleet: FleetApiController.java:176-220, FleetTaskPermissionService.java (GRANTABLE, assertMayPush, grantsForCurrentCaller), InstitutionTaskPermission.java, V9__institution_task_permissions.sql.

Verification

All 5 tabs parse under a faithful simulation of MarkdownGuideService.parse() (which differs from the reconciler's regex) — bodies intact, none skipped.
coverage-reconcile.py: 125 → 126 modules, no missing role-tabs.
Role matrix confirmed live against bcos.dev, not inferred from annotations:

Role	GET all	GET grantable	GET /mine	PUT
CUSTOMER	403	403	200	403
MSP_ADMIN	200	200	200	200

Note on the reconciler

coverage-reconcile.py could not have caught this gap. It checks services → technical.<svc>, agent modules → agent.<slug>, role-tabs on modules already in the guide, and SPAs with no content at all. That last check is all-or-nothing per app — fleet had 5 modules, so it passed. The script never enumerates SPA nav items, so a new module in an already-documented SPA is invisible to it. The same blind spot will swallow the next new tab in any documented app. Not fixed here; worth its own issue.

Deploy

Content only — no code, no schema. Stays on develop; not deploying without an explicit go, per standing rule.

Closes #23. `fleet.task-permissions` returned **404** — the Task Permissions tab shipped in hiveops-fleet#119 and is live on bcos.dev with no guide coverage at all. `fleet.tasks` mentions permissions exactly once and never describes the grant model. This is the setting that decides **which commands a customer may push to their own ATMs**. Deny-by-default, per-institution, per-command. Arguably the highest-consequence fleet setting we have, and it was the least documented. ### The 5 tabs | Tab | Covers | |---|---| | **Customer** | Grant/revoke, saves instantly with no undo, why only Reboot + Restart Agent are offered | | **Internal** | Triage for "customer cannot reboot", the two 403 messages and what each means, what we never widen, when to escalate | | **Architect** | Deny-by-default rationale, the two independent gates, two layers of refusal, replace-not-merge, why `GRANTABLE` is code not config, audit limits | | **Testing** | 8 checks against bcos.dev incl. the 400-on-`CONFIG_UPDATE` case, with restore steps | | **Claude** | Ownership, table, endpoint/role matrix, gotchas | ### Grounded in source Every claim traced to `hiveops-fleet`: `FleetApiController.java:176-220`, `FleetTaskPermissionService.java` (`GRANTABLE`, `assertMayPush`, `grantsForCurrentCaller`), `InstitutionTaskPermission.java`, `V9__institution_task_permissions.sql`. ### Verification - All 5 tabs parse under a faithful simulation of `MarkdownGuideService.parse()` (which differs from the reconciler's regex) — bodies intact, none skipped. - `coverage-reconcile.py`: 125 → **126 modules**, no missing role-tabs. - Role matrix confirmed **live** against bcos.dev, not inferred from annotations: | Role | GET all | GET grantable | GET /mine | PUT | |---|---|---|---|---| | CUSTOMER | 403 | 403 | 200 | 403 | | MSP_ADMIN | 200 | 200 | 200 | 200 | ### Note on the reconciler `coverage-reconcile.py` **could not** have caught this gap. It checks services → `technical.<svc>`, agent modules → `agent.<slug>`, role-tabs on modules *already in the guide*, and SPAs with *no* content at all. That last check is all-or-nothing per app — `fleet` had 5 modules, so it passed. The script never enumerates SPA nav items, so a new module in an already-documented SPA is invisible to it. **The same blind spot will swallow the next new tab in any documented app.** Not fixed here; worth its own issue. ### Deploy Content only — no code, no schema. Stays on `develop`; not deploying without an explicit go, per standing rule.

hiveiq added 1 commit 2026-07-16 14:45:18 -04:00

docs(guide): add fleet.task-permissions module (#23 ) 71d7b06dea

The Task Permissions tab shipped in hiveops-fleet#119 and is live, but had no
guide module at all — the API returned 404 for fleet.task-permissions, and
fleet.tasks mentions permissions once without describing the grant model.

This is the setting that decides which commands a customer may push to their own
ATMs: deny-by-default, per-institution, per-command. Highest-consequence fleet
setting we have, least documented.

Adds the 5 canonical role tabs, grounded in hiveops-fleet source:

- Customer  — grant/revoke, why only Reboot + Restart Agent are offered
- Internal  — triage for "customer cannot reboot", what we never widen
- Architect — deny-by-default rationale, the two independent gates, replace-not-
              merge semantics, why GRANTABLE lives in code
- Testing   — role matrix + the 400-on-CONFIG_UPDATE case, against bcos.dev
- Claude    — ownership, table, endpoints, gotchas

Verified: all 5 tabs parse under MarkdownGuideService.parse(); reconciler counts
126 modules with no missing role-tabs. Role matrix confirmed live on bcos.dev
(CUSTOMER 403/403/200/403, MSP_ADMIN 200/200/200/200).

Refs #23. Follow-up to hiveops-fleet#119, hiveops-fleet#100.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

johannes approved these changes 2026-07-16 14:49:00 -04:00

hiveiq merged commit e54b994391 into develop

2026-07-16 14:49:34 -04:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hiveiq-src/hiveops-guide#24