Skip to content

docs: propose Slack channel roles for teammates and maintainers - #23362

Open
mvn-bachhuynh-dn wants to merge 2 commits into
kirodotdev:mainfrom
mvn-bachhuynh-dn:docs/rfc-slack-channel-roles
Open

mvn-bachhuynh-dn wants to merge 2 commits into
kirodotdev:mainfrom
mvn-bachhuynh-dn:docs/rfc-slack-channel-roles

Conversation

@mvn-bachhuynh-dn

@mvn-bachhuynh-dn mvn-bachhuynh-dn commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record a proposed design for letting a single-owner gateway admit named Slack users with narrow, per-channel rights, so maintainers can accept, reshape or decline it before any code is written.

Slack is owner-only by construction today (is_allowed_user returns is_owner; slack.allowed_users is pruned to the owner at boot). A team running one Kiro Crew per project, one Slack channel per project, has no middle ground between "only the owner" and "any allow-listed user with the owner's power". Issue #22759 asked for this; the triage answer was to propose a design through the RFC process.

Why it matters

The change reverses a deliberate security default, touches the Slack gate, the tool gate, governance profile selection and the sandbox, and would be expensive to undo. GOVERNANCE.md's scope test puts that behind an RFC, and the First Principles lane needs an accepted document on the base before any implementing PR can land.

Not a goal

What changed (motivation → approach → change)

  • Motivation: Slack: per-channel roles (read-only members, channel maintainers, workspace confinement) #22759, plus findings from running the model as local patches on a 0.9.0 gateway with real users (five gate holes any design must close, listed in the document).
  • Approach: roles as governance profiles selected by the turn's sender and channel (a new principal bind type), so the evaluator stays POLICY ∩ PROFILE and a role is data; owner-only surfaces (DMs, buttons, linked slots, commands) stay owner-only; out-of-role calls become owner approvals in the thread; the maintainer fast path only for an OS-confined session.
  • Change: docs/request-for-change/rfc-slack-channel-roles.md (status draft, revision 2 audited at 9ae6bc7124, six ordered phases with exit criteria and stated dependencies, three open questions) and its row in docs/request-for-change/README.md.

Backwards compatibility

Compatible: documentation only; no code, config or behaviour changes.

Removes nothing: the PR adds one document and one index row.

Tests

N/A — documentation only. scripts/docs-lint.sh and scripts/check_brand_name.py pass on the change.

Manual verification

N/A — documentation only. Every statement about current code was checked against main at 7796e2af52 (definitions and callers), cited by symbol per the docs-lint rule.

Related Issues

Proposes a design for #22759. Related: #12673 (hosted multi-user, out of scope here).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

🤖 Generated with Claude Code

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Oct 23, 2026
@mvn-bachhuynh-dn
mvn-bachhuynh-dn force-pushed the docs/rfc-slack-channel-roles branch from e4e5b38 to 6ef3fad Compare October 23, 2026 07:39
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ⏭️ skipped

Revision e2ae29e63e1e52517146e6d067ebeb2758b19536 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision e2ae29e63e1e52517146e6d067ebeb2758b19536 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

Design-level review of e2ae29e63e1e52517146e6d067ebeb2758b19536 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

The RFC sets up a second Slack role system and never mentions the accepted roles model or the owner's earlier decision on the same issue, #22759, so the two designs conflict.

Blockers

Ignores accepted rfc-per-person-execution §7/R10, decision 2026-11-01-shared-crews-give-each-person-one-role, and rfc-slack-shared-access
Trigger: a maintainer accepts this draft, and the phases are built as written: "One dedicated file under the data home (working name slack_roles.json)" plus "Add one bind type, principal, to Bind.type".
Outcome: role data ends up in two places. The accepted design already has keystone people_policy.json roles, each with a governance profile and run_as, and this adds slack_roles.json with its own principal bind. Under this RFC, teammate turns run in the gateway's own account, which R10 forbids ("Unknown people are never the owner") and which this RFC never names as an exception. The repo owner already settled #22759 as an explicit act-as-owner opt-in (rfc-slack-shared-access). → Two accepted documents would contradict each other, and implementing PRs would be gated on whichever one the lane reads.
Fix: map teammate and maintainer to roles in people_policy.json, with a Slack principal, a per-channel profile and run_as: guest|self. If you keep the separate file, add a section on how this relates to R10 and rfc-slack-shared-access, and put the accepted roles model under Alternatives with the reason it was rejected.
Clears when: the RFC reconciles with rfc-per-person-execution §7/R10, the 2026-11-01 decision and rfc-slack-shared-access (by reusing them, or by stating which parts it supersedes and why), and is re-verified against current main.

Notes

  • "Teammate" already means a Shared Crew person (shared_crew/teammate_access.py), so choosing that word to avoid the clash with "member" just creates a different clash.

[DESIGN-REVIEWED] e2ae29e

Description read

[DESCRIPTION-READ] b024d330385a922b23759a6192130745bcf7c6b7c592711d56e4dda0e04a7775

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — 🔴 changes requested (blocking)

Reviewed e2ae29e63e1e52517146e6d067ebeb2758b19536 via the fork AI-review pipeline; updated in place on each push.

The RFC's "Current state" section and its README row say Slack is owner-only, but the base tree already ships slack.shared_access, which lets listed non-owners drive the bot with the owner's identity. The role design never says how roles combine with shared access.

BLOCKING — docs/request-for-change/rfc-slack-channel-roles.md:87
- A non-owner's message is refused at the events layer: / `_route_message` in `slack/events.py` gates on `is_allowed_user` (also lines 80, 150, 269–270, 377–378, and README.md row "Nothing built … is_allowed_user … returns is_owner")
Trigger: an operator turns on slack.shared_access.enabled and lists a teammate (base: slack/shared_access.py:3-6), then adds this RFC's role file. On base, events.py:653 admits the sender through is_allowed_user(sender_id) or is_shared_user(sender_id). interactions.py:695 lets a shared user press approval buttons, and :719 refuses that only for Trust or someone else's ask. So the requester can approve their own card.
Outcome: The document records a false reading of main. Goal 1 ("byte-identical to today: owner-only"), Backward compatibility, and the rejected "Honour the allow-list only" alternative all ignore a feature that already exists. Its "Only the owner can click (the is_allowed_user check …)" claim does not hold on base. The design leaves open whether someone listed in both shared_access and the role file gets full owner power or the narrowed role. If owner power wins, the POLICY ∩ PROFILE ∩ ROLE narrowing and Goal 5's owner-approval guarantee are bypassed at the multi-human allow-list boundary.
Anchor: defect
Fix: Re-measure against current main and rewrite "Current state" and the README row to cover slack.shared_access. State how roles relate to it: they replace it, they refuse to load next to it, or they always narrow a shared user. Require role-originated cards to resolve only through is_owner, not through the is_allowed_user/is_shared_user admission at interactions.py:695.

[BLOCK-MERGE] e2ae29e
[OPUS-REVIEWED] e2ae29e

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed e2ae29e63e1e52517146e6d067ebeb2758b19536 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e2ae29e

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Oct 23, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Deep review found no code inconsistency, but this pull request defines new Slack channel roles for teammates and maintainers. It changes the team communication and authority model, so the design needs a maintainer decision rather than an automated approval.

design-doc-gate: Rule D — this changes a design document, so it needs a human to agree to the design. Not approved and not rejected by this review.

@iamwhatever

Copy link
Copy Markdown
Contributor

Hold at 6ef3fad.

This is a draft RFC that would reverse Slack's owner-only default and change governance profile selection, so a maintainer has to accept or reshape the design. Nothing automated can approve that. Two concrete points from the Design Review notes have no reply yet:

  1. The principal bind is selected before app/task/surface (rfc-slack-channel-roles.md#L174). That replaces a tighter app or task profile rather than intersecting with it, so a teammate turn could get more than the owner's own turn. Please say whether the role profile should intersect with the app/task profile.
  2. Open question 1 offers config.json for role data (#L306), but the RFC's own rule requires role data the agent cannot write. Please drop that option or explain how its write path is fenced.

Two checks are red on this head: Dependency License Gate ("Dependency review is not supported on this repository") and Sensitive Change Review ("Could not read the PR from the API; re-run this job"). Both look like infrastructure failures and should pass after a re-run. To clear this hold: answer the two design notes and get a maintainer's design acceptance.

— crew-pr-reviewer (r123)

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 24, 2026
@mvn-bachhuynh-dn

Copy link
Copy Markdown
Contributor Author

Thanks. Both design notes are addressed in revision 2 (head 6c0ff0502f, still one commit; re-verified against main at 9ae6bc7124):

  1. The role profile now intersects; it never replaces. resolve_active_scope keeps choosing the app, task or surface profile exactly as today; for a non-owner principal the gate also resolves the role profile and permits an item only if both permit it, reusing the evaluator once per profile:
    effective = POLICY ∩ active profile (app | task | surface) ∩ role profile.
    So a teammate or maintainer turn can never get something the owner's own turn in the same context would be refused. Phase 2 gains the matching exit criterion: for every scope in SCOPE_CATALOG, a test proves a role turn is never permitted an item the owner's turn in the same app/task/surface context is refused.

  2. config.json is dropped as an option. Role data lives only in a dedicated file (working name slack_roles.json), fenced on each write path:

    • the leaf joins _CREW_READONLY_LEAVES (sandbox_leaves.py), so a write from inside the sandbox is a kernel denial in every sandbox mode, covered by the union pin in test_sandbox_governance_mask.py;
    • is_sensitive_write_path refuses the file-edit tool on it;
    • with agent.sandbox: off roles are not admitted at all (a spawned shell could reach any file), so a non-empty role file leaves Slack owner-only and the gateway logs why.

    Its only writers are owner-only gateway surfaces outside the sandbox. This also removes the old open questions 1 (where role data lives) and 4 (migrating stale slack.allowed_users): those keys stay ignored, so nothing needs migrating.

On the two red checks (Dependency License Gate, Sensitive Change Review): agreed they look like infrastructure failures; I cannot re-run them from the fork, so they need a maintainer re-run.

I'm happy to reshape further before a design decision; the remaining open questions are confinement, memory scoping, and whether the owner-approval cards should also replace today's per-tool card.

@mvn-bachhuynh-dn
mvn-bachhuynh-dn force-pushed the docs/rfc-slack-channel-roles branch from 6ef3fad to 6c0ff05 Compare October 24, 2026 07:39
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 24, 2026
@mvn-bachhuynh-dn
mvn-bachhuynh-dn force-pushed the docs/rfc-slack-channel-roles branch from 6c0ff05 to 9bbee40 Compare October 24, 2026 07:46
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 24, 2026
@mvn-bachhuynh-dn

Copy link
Copy Markdown
Contributor Author

Rebased onto current main to clear a conflict in the RFC index (docs/request-for-change/README.md audit paragraph); head is now 9bbee40730, still one commit. The document is unchanged from revision 2 above.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 24, 2026
@mvn-bachhuynh-dn
mvn-bachhuynh-dn force-pushed the docs/rfc-slack-channel-roles branch from be753d9 to a5b796e Compare November 11, 2026 07:00
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 11, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-slack-channel-roles branch from a5b796e to 8b350a6 Compare November 14, 2026 11:17
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 14, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider raised 1 possible problem and estimates a 62% chance that this change introduces a defect; a person should check it.

This is a docs-only PR that adds a draft RFC for Slack channel roles and its README index row. What it says about the current code is accurate. But it was written and audited before rfc-per-person-execution was accepted on base (2026-11-01), and it never mentions that RFC. The accepted RFC decided there should be one role model shared with this Slack RFC. It also already fixed the role file (people_policy.json), how a channel user is identified (DM link plus dashboard sign-in, otherwise guest), and who approves (the run-as person, or a holder of people.manage for out-of-role asks). This draft proposes a separate slack_roles.json, identity from the raw Slack user id, and owner-only approval, and its index row asks for acceptance. Landing it as written would put two conflicting designs for the same trust boundary on base. It should be reconciled with the accepted RFC first, either as an amendment to it or with each divergence stated and argued.

Things to check (possible problems the decider raised; at this confidence many turn out to be fine):

  • The RFC proposes a second role model and a different trust and identity binding for Slack users, which contradicts a decision already accepted on base that says both should be one role model. If this lands with its README row asking for acceptance, a maintainer could accept a design that the accepte (docs/request-for-change/rfc-slack-channel-roles.md, medium)

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 8b350a6d10 · 371 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 14, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This adds a new concept, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

Review result on this head: no blocking defect. The PR changes only docs: the new RFC and one row in the index. I checked the current-state claims against main and they hold. is_allowed_user checks the owner only, the orchestrator init prunes allowed_users to the owner, Bind.type is surface | app | task, and _CREW_READONLY_LEAVES and is_sensitive_write_path exist. The rule that a role intersects the active profile and never replaces it is sound, and so is fail-closed role evaluation. This RFC widens who can drive the agent from Slack, so the maintainers and the security reviewer make that decision. This review does not.

Optional notes for the next revision:

  • The accepted rfc-per-person-execution.md on main already plans one shared role model with this RFC. It uses people_policy.json, a dashboard-bound Slack identity where an unbound user is a guest, and it routes out-of-role asks to a people.manage holder. This draft does not name that RFC. It proposes its own slack_roles.json, raw Slack user ids and owner-only approval. Consider rewriting it as the channel side of that model, or add a section that names each difference and argues for it.
  • Open PR feat(slack): let the owner share Slack access with named people, off by default #30760 proposes a different design for the same issue Slack: per-channel roles (read-only members, channel maintainers, workspace confinement) #22759, in which a shared user acts as the owner. Each document could name the other so a maintainer can sequence them.
  • The audit stamps (revision: 2, last-audited: 2026-10-24, and "Verified at 9ae6bc7124" in the index row) predate the 2026-11-07 change and the accepted per-person RFC. Bump them when you re-audit.

For the security review:

  • A second keystone role file would need its own READONLY fence, write-gate row and sandbox-off refusal. Reusing people_policy.json avoids that.
  • Slack identity: the draft trusts the raw event user id plus a users.info cache. Main's accepted design requires a sign-in binding before a channel user gets any role.
  • Shared threads: an owner turn later in a thread a teammate posted in runs under the owner's full profile, with the teammate's text in its context. The Security considerations section does not cover this path.
  • Role evaluation must fail closed at a gate that otherwise fails open. The draft states this rule, and Phase 2 needs to test it.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 14, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-slack-channel-roles branch from 8b350a6 to c164cbf Compare November 17, 2026 22:38
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Nov 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Stale-PR cleanup note: every other check on this head passes. The fork Security Scope Review lane failed twice (run https://github.com/kirodotdev/KiroCrew/actions/runs/44194792125, first attempt and one rerun) because the workflow's GitHub App hit the installation API rate limit (API rate limit exceeded for installation), not because of anything in this PR. A maintainer needs to rerun that lane once the limit has reset. Nothing is needed from the author.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 18, 2026
mvn-bachhuynh-dn and others added 2 commits November 19, 2026 18:30
RFC for kirodotdev#22759: let a single-owner gateway admit named Slack users with
narrow per-channel rights (read-only teammates, open channels,
per-channel maintainers confined to the channel's workspace, owner
approvals in the thread), expressed as governance profiles selected by
the turn's sender, so the evaluator stays POLICY ∩ PROFILE. Draft;
nothing built. Owner-only behaviour is unchanged with no roles set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s checks

- Specify role-profile evaluation fails closed on PreToolUse hooks error
- Add exit criterion in Phase 2 for harness declaration and refusal when unconfined

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@iamwhatever
iamwhatever force-pushed the docs/rfc-slack-channel-roles branch from c164cbf to e2ae29e Compare November 19, 2026 18:32
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 19, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Stale-PR cleanup note: rebased onto current main as e2ae29e (the only conflict was the RFC index in docs/request-for-change/README.md; both sides kept). CI and the other review lanes pass on this head.

The Opus 5.5 Review now blocks on a design point, not a mechanical fix: main ships slack.shared_access and the accepted rfc-per-person-execution / rfc-slack-shared-access, and this RFC's Current state and role model do not account for them. Choosing how roles relate to shared access (replace it, refuse to load beside it, or always narrow a shared user) is the author's decision. @mvn-bachhuynh-dn, could you revise the RFC to reconcile with those documents? A maintainer design sign-off is still needed after that.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants