Skip to content

docs(rfc): channel card catalog for Slack, Teams and Discord cards - #34612

Merged
bolichen97 merged 2 commits into
mainfrom
docs/rfc-channel-card-catalog
Nov 11, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
docs/rfc-channel-card-catalog

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

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

  • Any code change. This PR adds a design document and its index row only.
  • Adopting json-render, the Chat SDK or a Node runtime. json-render is credited as prior art only.
  • Deciding the open questions; they are listed for Kyle.

What changed (motivation → approach → change)

  • New docs/request-for-change/rfc-channel-card-catalog.md (status draft, verified at b58eef1f9c). It surveys the hand-built builders on main and in the open Slack Code PRs, ties each bug class to PRs, and proposes:
    • a typed spec (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;
    • one 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;
    • an optional agent path that returns issues to the model, in-place edits behind the existing commit_if_not_stopped fence, and a plain-text fallback;
    • a six-phase migration that starts with the Stop/working cards and proves each move with golden JSON. Phases 1 and 2 change no output.
  • 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.sh passes, and the local pre-push gate passes against origin/main.

Manual verification

N/A — docs only; the RFC's code claims were checked against main at b58eef1f9c and the open PR heads it names.

Related Issues

None.

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

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners November 10, 2026 15:35
@kyleseaman
kyleseaman requested a review from Zedmor November 10, 2026 15:35
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 10, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 5d92eac15f95974b8e259f5a57a2bf438c048900 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 Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 5d92eac15f95974b8e259f5a57a2bf438c048900 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 Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 5d92eac15f95974b8e259f5a57a2bf438c048900 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 .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 Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 5d92eac15f95974b8e259f5a57a2bf438c048900 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5d92eac

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5d92eac15f95974b8e259f5a57a2bf438c048900 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 5d92eac15f95974b8e259f5a57a2bf438c048900 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5d92eac

Verdict parsed from the review's SHA-scoped output markers for commit 5d92eac15f95974b8e259f5a57a2bf438c048900.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 5d92eac15f95974b8e259f5a57a2bf438c048900 false-positive: <reason, 20 to 500 characters>

@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 labels Nov 10, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-channel-card-catalog branch from df73fb2 to 68db859 Compare November 10, 2026 19:59
@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 10, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Automated, not a person, and not a review: a maintainer still decides.

decider-v3c@217fe607 · p_defect 0.04 · router R0 (approves only when p_defect <= 0.12, on changes of at most 400 changed lines) · head 68db859881 · 538 changed lines

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.

@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 10, 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 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 display_safe_for, readings_hide_secret, commit_if_not_stopped, blocks_request_remote_media and _FLAG_SUPPRESS_EMBEDS. The cited audit commit is an ancestor of the merge base. The docs lint passes on the head tree, and the README edit merges cleanly with current main. One thing done well: every migration phase can be abandoned on its own, each has an exit criterion proven by golden fixtures, and caps are measured after redaction.

Optional:

  • Phase 1 working-card golden: the "Link to Dashboard" button on main has no value key, and the actions block has no block_id. Button.value is a required str in the spec. Consider defaulting it to "" and saying that the Slack renderer leaves out an empty value and an empty Actions.id, so the golden can pass unchanged.
  • Goals and Backward compatibility list one output change. The Security section adds a second one: wider split-secret screening can refuse a card that posts today. Consider naming it in both sections and saying what the user sees instead.
  • The agent card path (section 4, Phase 6) and Webex go past the goal's three platforms. They are already marked optional. Moving them to an open question or a future work paragraph would keep the main design tight.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

  1. 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 declared Fit.SPLIT or Fit.MARKED where 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.

  2. 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.

@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: passed Eligible automated validation passed for the current revision labels Nov 10, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-channel-card-catalog branch from 68db859 to 5d92eac Compare November 11, 2026 01:12
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 11, 2026
@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 labels Nov 11, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author

@bolichen97 thanks. Both conditions are now in the RFC as written, at 5d92eac15f95974b8e259f5a57a2bf438c048900. The edits are only that top commit. The commit under it is the content you reviewed, rebased onto main with no changes to the RFC file.

  1. Refusing over-long text. Section 3, "Every field says what happens over its cap", now lists four fits. Fit.REFUSE is the default only for a new card and for every agent card. A migrated builder declares the fit it has today: Fit.SPLIT where it splits, Fit.MARKED where it marks, and a new Fit.CUT(n) that keeps today's plain cut byte for byte. Examples are wrap_up_blocks' 2,800, its 200-character fallback, and the 75- and 80-character labels. Refusal on a migrated card is opt-in, field by field. Over-cap issues are only logged unless the fit is REFUSE. Phase 2 now keeps the wrap-up cut, and its goldens are unchanged even over 2,800. Phase 3 keeps the Slack "…" label as MARKED and the Discord 80-character cut as CUT(80). Phase 5 keeps the board's [:2900] as CUT(2900). The Summary, Goals, Backward compatibility, Testing and the "Clamp silently" alternative say the same thing.

  2. Wider secret screening. Section 3, render step 3, now runs the split-secret and character-reference screens where they run today: agent-authored views, plus the new agent cards. A gateway-built card gets them only through a setting that is off by default. With the setting off, a card that posts today is never refused by them. The "Secret screening keeps its scope" bullet under Security considerations and the redaction property test match this. Running those screens report-only on gateway-built cards is now Open question 7, as a possible later step. It is not a default.

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.

@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 11, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.REFUSE is 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 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Arming auto-merge on the approved head. The head is unchanged since my approval and all checks are green.

@bolichen97
bolichen97 merged commit d3803a3 into main Nov 11, 2026
156 of 164 checks passed
@bolichen97
bolichen97 deleted the docs/rfc-channel-card-catalog branch November 11, 2026 04:18
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 11, 2026
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.

3 participants