Repository navigation
docs(rfc): channel card catalog for Slack, Teams and Discord cards - #34612
Conversation
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS This PR only adds a draft RFC and its index row, with no code or default changes. It removes nothing, and it considers alternatives and lists open questions. [DESIGN-REVIEWED] 5d92eac Description read[DESCRIPTION-READ] f8189193c90710f0633b4bde20ab82ace3f4ace440d1bd81bad8e6c621d5530d 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 |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
df73fb2 to
68db859
Compare
Code change approver recommendation: A person should decideAutomated, not a person, and not a review: a maintainer still decides.
Why: 538 changed lines > 400 (small/medium only). Docs-only PR adding a draft RFC for a shared, validated, redacted channel card spec plus its README index row. Spot-checked code claims against repo/src: wrapup MAX_SUMMARY_CHARS=2800 with silent [:2800] and [:200] cuts, slack/blocks.py Stop/working builders, commit_if_not_stopped, readings_hide_secret, blocks_request_remote_media, display_safe_for, _lossless_blocks, _refuse_hidden_split, _bar_items, _BACKTICK_PAIR_RE, _FLAG_SUPPRESS_EMBEDS, _DELIVERY_SINKS and the 1.0/1.2/3.0 s edit intervals all exist as described. The proposed design only tightens trust boundaries: no media, preview or free-URL elements; links come only from gateway builders; buttons carry lookup keys only; agent cards are display-only; redaction runs on every field; limits are measured after redaction; the Stop fence calls commit() with no await before the write; posture rows are only added, and that is raised as an open question. No code, config or behaviour changes. CI pre-merge checks and AI lanes are clean. If this recommendation is wrong, reply here; the replies are how the approver is evaluated. |
|
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 findings. The PR changes docs only. It adds the RFC and one index row and note in the RFC README. We spot-checked the RFC's claims about the code against current main, and the symbols it cites are there, for example Optional:
|
bolichen97
left a comment
There was a problem hiding this comment.
Read the whole diff: the new RFC and the README row. This is a comment, not an approval, because the sign-off on a design of this size is the maintainer's.
What it proposes
One typed card spec (Card, Section, Text, Fields, Table, Context, Divider, Actions, Button) and one render(spec, platform, limits) that redacts every field, checks every platform cap and returns Slack, Teams, Discord or plain-text output. Six phases move the hand-built cards over one surface at a time, each proven by golden JSON. Phase 6 is an optional display-only card tool for agents.
Pros
- One place for redaction, mention defusing and limits, so a new card cannot forget them. The bug classes it lists are real: cuts at a platform cap, a field lost on rebuild, and a redaction miss.
- A rebuilt card is a new spec, not an edit of posted JSON. The approval builder takes the MCP identity as a required argument.
- No image, video, preview or free URL in the element set, so no new fetch path.
- Each phase is one PR and can be dropped on its own.
Cons and risks
- It touches about 25 modules and three platforms, and the Slack code-channel work is still moving, so rebase cost is real.
- Two behaviors are new restrictions: a card over a cap is refused instead of cut, and the split-secret and character-reference screens now run on every card. The RFC says this "can refuse a card that posts today". That adds strictness to paths that work now.
- Phase 3 depends on adding a Select element, which is still an open question.
- It adds a row to a watched security-posture file.
Tech debt
It removes duplicated builders over time, but the old and new paths coexist until Phase 5 finishes, and any phase left undone leaves two ways to build a card.
Recommendation
Direction is sound. Sign Phases 1 and 2 only, with one condition: keep today's behavior for any card that posts now. Over a cap, use the declared split or marked fit by default, and put the refusal and the wider secret screen behind an off-by-default setting, or apply them only to new cards and agent cards. Decide Phase 3 onward after Phase 1 lands.
I did not run anything locally. This is a docs-only change.
bolichen97
left a comment
There was a problem hiding this comment.
The direction in this RFC is signed for phases 1 and 2. Phase 3 and later will be signed after phase 1 lands. Two parts of the design tighten what the gateway does today, and they need a change before the document can be approved.
-
Refusing over-long text. Section 3 ("Limits never truncate silently") and the first Goal make a card that is over a platform cap fail with a
CardError. Today some builders cut or split the text and the card still posts. Please change the default so a card that posts today still posts: use the declaredFit.SPLITorFit.MARKEDwhere the builder does that now, and keep today's cut where it exists. A refusal on breach can stay as an option, off by default, or apply only to new cards and to agent cards that have no behavior to keep. -
Wider secret screening. Step 3 of the render order and the "Wider screening" bullet in Security considerations run the split-secret and character-reference screens on every card. The RFC says this "can refuse a card that posts today". Please keep those screens where they run now (agent-authored views) and put the wider run behind a setting that is off by default, or run it for new cards only. A match on a card that posts today should keep today's behavior.
The redaction and mention defusing that every card already gets, the length checks that only report issues, and the no-media element set are fine as written.
Once the document says this, I will approve.
68db859 to
5d92eac
Compare
|
@bolichen97 thanks. Both conditions are now in the RFC as written, at
The redaction, mention defusing, report-only length checks and the no-media element set are unchanged. The direction note at the top records the sign-off for Phases 1 and 2, with Phase 3 onward decided after Phase 1 lands. |
bolichen97
left a comment
There was a problem hiding this comment.
Re-read the new head. Both conditions from my earlier review are now in the document, so I am approving.
- A card that posts today keeps today's behavior over a cap. Each migrated builder declares the fit it has now (
Fit.CUT(n),Fit.MARKED,Fit.SPLIT).Fit.REFUSEis the default only for new cards and agent cards, and changing an existing cut is a separate decision per surface. - The split-secret and character-reference screens stay where they run today (agent views, and now agent cards). Gateway-built cards get them only when a setting, off by default, turns them on. With it off, a card that posts today is never refused.
- Phases 1 and 2 keep their goldens unchanged, over-cap text included. The Backward compatibility, Security considerations, Testing and Alternatives sections agree with this, and open question 7 records the report-only option as a later step with no default change.
- The Review line records that the direction is signed for Phases 1 and 2, and that Phase 3 onward is decided after Phase 1 lands.
Docs only. I did not run anything locally.
bolichen97
left a comment
There was a problem hiding this comment.
Arming auto-merge on the approved head. The head is unchanged since my approval and all checks are green.
Problem / Motivation
Goal: Record a proposal for one validated, redacted card spec that renders Kiro Crew's Slack, Teams and Discord cards, so Kyle can review the design before any code is written.
Every chat card is built by hand, per surface and per platform. The Slack Code PRs keep hitting the same four bugs: text cut mid-sentence at Slack limits (#21991 UX rounds), a field dropped when a card is built a second time (the MCP identity line on #21991's worker-approval relay), redaction or mention defusing missed on some paths (#21429, #22001), and Stop/commit races at the send site (#21429). Each fix lands in the module that found it, so the next card starts over.
Why it matters
Each new card surface (board, tabs, pickers, relays) repeats review rounds on the same classes, and a missed redaction or a dropped identity line on an approval card is a security problem, not just a UX one. Agreeing on one spec and one render path first lets the migration land as small, behaviour-preserving PRs.
Not a goal
What changed (motivation → approach → change)
docs/request-for-change/rfc-channel-card-catalog.md(statusdraft, verified atb58eef1f9c). It surveys the hand-built builders on main and in the open Slack Code PRs, ties each bug class to PRs, and proposes:Card,Section,Text,Fields/Field,Table,Context,Divider,Actions/Button) with images, video, previews and free URLs left out, and links only from gateway builders;render(spec, platform, limits)that redacts and defuses every field and checks every platform cap. A card that posts today keeps its current cut or split through a declared fit, and new and agent cards refuse with structured issues. The split-secret and character-reference screens stay on agent views and agent cards, with an off-by-default setting for the rest;commit_if_not_stoppedfence, and a plain-text fallback;docs/request-for-change/README.md: the index row and the "row was added" note.Backwards compatibility
Compatible: docs only; no code, config or default changes.
Removes nothing: the diff only adds a document and an index row.
Tests
Proof: not provable -- docs or config only
./scripts/docs-lint.shpasses, and the local pre-push gate passes againstorigin/main.Manual verification
N/A — docs only; the RFC's code claims were checked against main at
b58eef1f9cand the open PR heads it names.Related Issues
None.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)