Skip to content

feat(cards): channel card catalog Phase 1 for Stop and working cards - #35974

Merged
bolichen97 merged 2 commits into
mainfrom
feat/card-catalog-phase-1
Nov 13, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
feat/card-catalog-phase-1

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Slack cards come from one typed card spec and one render path that redacts, defuses mentions and checks Slack's caps, starting with the Stop and working cards, with no change to what Slack shows.

Today every Slack card is hand-built Block Kit JSON. Each builder does its own redaction, mention defusing and length cuts, so a new card can forget a step. The channel card catalog RFC (merged 2026-11-11) replaces that with a spec and a render() that runs every step for every card. This PR is its Phase 1.

Why it matters

The Slack Code PRs keep hitting the same four kinds of bug (text cut mid-sentence at a cap, fields dropped on a rebuild, redaction or defusing missed on one path, writes racing a Stop). Each fix stays in the module that found it, so the next card starts over. Phase 1 lands the package and proves it on four low-risk cards, so later phases can move the cards that hold model text.

Not a goal

  • Wrap-up cards (Phase 2), OPTIONS and approval cards, the code-channel board, tabs, bar and pickers, and agent-authored cards.
  • Teams, Discord and Webex renderers (Phase 3).
  • Any wording, layout, action id, value or block id change on any card.
  • A setting for the split-secret screen. It lands with the first phase whose cards carry variable text.
  • Fit.SPLIT. It lands with the first card that uses it.

What changed (motivation → approach → change)

Approach. Follow the RFC's design, shipping only what the four cards use. Every spec type, fit and render step in this PR is reached by at least one of the four builders.

Narrowed after First Principles review. The first head of this PR (a95c896317) also carried send.py (post_card/edit_card), links.py, a plain-text renderer, the split-secret step and more elements and fits. First Principles blocked it because none of those had a caller. The team lead agreed, so they are removed, not overridden. Each now lands with the first card that uses it, and the RFC's Migration plan names that phase:

  • send, its commit-point tests and the plain-text renderer: Phase 2.
  • The split-secret step and its setting: Phase 2, the first card with variable text.
  • Fit.CUT and Confirm: Phase 2.
  • Fit.MARKED: Phase 3.
  • The code text style: Phase 4.
  • Links, Fields, Table, Divider, titles, the plain style and the primary button style: the first card that uses each.

New package src/kiro_crew/messaging/cards/:

Module What it holds
spec.py Frozen dataclasses Card, Section, Context, Text, Actions, Button; Fit (REFUSE, KEEP); Issue; CardError. No element can express an image, a video, a link preview or a URL.
render.py render(spec, Platform.SLACK, limits=None). A Text's runs are joined and redacted as one string, through display_safe_for with redact_via_context and the mention defuse. A button label gets the same treatment. Then Slack mrkdwn escaping and **bold** → *bold*, and Slack's caps measured on what Slack receives. Every string placed in the payload then passes one last check in the form it ships (_Pass.emit): if redaction would still change what the reader sees, the card is refused. A string that shows nothing once redacted is refused. A breach under Fit.REFUSE raises CardError with every Issue (path, code, limit, actual). Fit.KEEP logs it and sends the value unchanged.
limits.py SLACK_LIMITS, Slack's own documented caps: 50 blocks, 3,000 section and context text, 10 context items, 25 buttons, 75 label, 2,000 value, 255 action and block id.

slack/blocks.py. build_stopping_blocks, build_stopped_blocks, build_stop_failed_blocks and build_working_blocks are card specs rendered by render. Signatures, action ids, values and block ids are unchanged, and no caller changes. Each field's declared fit:

Builder Spec Fits
build_stopping_blocks(key) Section(Text("⏹ **Stopping…**\nCooperative cancel in progress.")), Actions(id="stop-actions-{key}", Button("Kill Now", "stop_kill_now", value=key, danger)) text REFUSE; button and block id KEEP
build_stopped_blocks() Section(Text("⏹ **[Stopped]**")) REFUSE
build_stop_failed_blocks() Section(Text("⛔ **[Stop Failed, Session Reset]**")) REFUSE
build_working_blocks(key, include_dashboard_link=) Context(Text("⏳ _Working…_")), Actions(Button("⏹ Stop", "mc_inline_stop_{key}", value=key, danger), plus Button("Link to Dashboard", LINK_DASHBOARD_ACTION) when asked) text and dashboard button REFUSE; Stop button KEEP

Decisions made while building (team lead, 2026-11-12), also in the RFC's Phase 1 text:

  • Goldens compare content, not key order. One spec cannot reproduce the three key orders the hand-built buttons used: Kill Now listed style before text, Stop listed text, value, style, and Link to Dashboard listed text before action_id. The goldens therefore assert dict equality and byte-equal sorted-key JSON. Slack reads a JSON object by key, so the order has no effect. A grep of src/ found nothing that hashes, fingerprints or string-compares these payloads. The builders' output goes straight to post_ephemeral, post_blocks or a response_url POST. The only json.dumps(blocks) near them (handler_runtime/stream.py _blocks_with_run) is a deep copy.
  • A builder never raises where main returned blocks. The text is constant and far under every cap. The one variable input, the session key, has no length bound in code: a linked owner key or a thread ts can reach these builders, and no validator caps either. So the session key's three fields (action id, block id, button value) declare Fit.KEEP: an over-cap value goes out unchanged, as the hand-built payload sent it, and the issue is logged. The "Link to Dashboard" button is constant (label and action id, no value, no URL).
  • Neutral package. messaging may not import a channel package (test_messaging_import_purity.py). The Slack escape is a local copy of escape_mrkdwn's three replacements, pinned to it by a test. Slack's mention grammar is pinned to SLACK_CAPABILITIES. The remote-media backstop is the Slack client seam (blocks_request_remote_media on post_blocks and update_message), which every send already passes. The no-media test runs that same check over the renderer's output.
  • No posture row in this PR. With the narrowed scope, render.py redacts only through display_safe_for. The redaction-sink registry's call check does not count that as a redactor call; messaging/inbound_spool.py, which also redacts only through it, has no row either. So test_security_posture.py asks for no row, and this PR touches no Sensitive Change Review file. The "Channel cards" row lands with the first phase whose render path calls a redactor directly.

Docs: docs/system-specs/modules/messaging.md (files row and a "Channel cards" section), slack-gateway.md (the slack/blocks.py row), the RFC's status, Phase 1 and 2 text, Security considerations and Testing wording, and its index row in docs/request-for-change/README.md.

Backwards compatibility

Compatible: the four builders keep their signatures and return payloads equal to the goldens captured on main, so every caller and click handler sees what it saw before.

Removes nothing: no function, key, row or behaviour is removed. slack/blocks.py stops importing build_link_dashboard_button, which stays in slack/format.py for its other callers, and a test holds the working card's dashboard button equal to it.

Tests

  • test/fixtures/channel_cards/slack_stop_working_goldens.json: captured from main 9e9de7bfc9 in the first commit, before slack/blocks.py changed. It holds all four builders, including both build_working_blocks variants.
  • test/test_channel_cards_slack_builders.py:
    • Each builder equals its golden, as a dict and as sorted-key JSON.
    • For session keys that are empty, a ts, exactly at the action-id cap, 2,500+ characters (past every Slack cap) and full of markup, each builder returns main's payload by its formula, never raises, and logs only when over a cap.
    • The dashboard button equals build_link_dashboard_button().
    • The local escape matches escape_mrkdwn, and the mention grammar matches SLACK_CAPABILITIES.
    • The builders hold no hand-built "type" literal.
  • test/test_channel_cards_render.py:
    • Redaction property. The corpus is a credential, a **-split key, <!channel>, <@U…>, @everyone, nested character references and backtick runs, in a section, a context line and a button label. Every display string is settled: display_safe_for with no mention grammar leaves what Slack shows unchanged (it is not idempotent on @, so the check has two parts), no live mention remains, and the key never shows. A key or a <!channel> split across a Text's runs is redacted or defused. emit refuses a string that shows a key.
    • Limits. For each cap (section, context, label, value, action id, block id), the spec renders at the cap and refuses one over with the expected path and too_long. Each count (blocks, context items, buttons) renders at the cap and refuses one over (too_many) and zero (empty). Fit.KEEP sends an over-cap action id, value and block id unchanged and logs them. A redaction placeholder can push text over the cap, and so can escaping.
    • Structure. Empty, ANSI-only and control-comment text, an empty label or action id, a wrong type, an unknown button style and a dict value are refused with their paths.
    • No media. No generated output satisfies blocks_request_remote_media, and the spec defines no media, preview, link or URL element.

Proof: not provable -- other: a refactor with no behaviour change; the goldens are the proof

Manual verification

Not done: I did not post these cards to a real Slack client. The goldens show the payloads are equal to main's, so a real client renders them the same.

Related Issues

RFC: docs/request-for-change/rfc-channel-card-catalog.md, Phase 1.

No issue is linked: Kyle asked for this directly, and tracking issues are opened only when he asks.

Checklist

  • At most two commits, with a Conventional Commits title
  • 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 12, 2026 17:52
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

  • No sensitive path changed; nothing to check.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision ef9118ca57156210cd85760c89ebbc21ccd07cc3 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 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ef9118ca57156210cd85760c89ebbc21ccd07cc3 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Three small surfaces have no caller or repeat an existing helper, and all three can be removed later.

Notes

  • Item 5 — duplicate of src/kiro_crew/slack/format.py:937 build_link_dashboard_button, which handler_runtime/finalize.py still calls at 2 sites. The diff hunk Button(label="Link to Dashboard", action_id=LINK_DASHBOARD_ACTION, ...) spells the same button a second time, and only a test holds the two equal. Subtraction: defer this button until the phase that moves finalize.py's footer, which then deletes the format.py helper.
  • Item 6 — zero consumers: the grep limits= over src/ finds 0 callers of render(..., limits=...) (tests are not consumers). Subtraction: delete the limits parameter and read SLACK_LIMITS directly.
  • Item 7 — one consumer, generalized: Platform has one variant (SLACK), and _CAPABILITIES and _DEFAULT_LIMITS are one-entry dicts keyed by it. Subtraction: drop the enum and both dicts until Phase 3 adds a second renderer.

What this change ships

Inventory (9 items) — 6 justified

Intent: let a maintainer build Slack cards from one typed spec through one redacting, cap-checking render path, starting with four constant cards. This is an ADDITION (a staged refactor).

  1. The Stop, Stopped, Stop Failed and Working cards are built from specs; Slack sees the same content, with button keys in a different order — justified
  2. A new neutral card package (spec, render, Slack caps) that other builders can call — justified
  3. An over-cap session-key id or value is now logged, then sent unchanged — justified
  4. A card whose text would show a credential, or show nothing, is refused — justified
  5. The working card's dashboard button is a second spelling of the format.py helper — duplicate of slack/format.py build_link_dashboard_button
  6. A caps-override parameter on render — zero consumers
  7. A platform enum and per-platform tables, each with one entry — one consumer, generalized
  8. A local copy of the Slack mrkdwn escape, held equal to escape_mrkdwn by a test — justified
  9. The RFC's status moves from draft to in-progress and its Phase 1 text is rewritten — justified

[FIRST-PRINCIPLES-REVIEWED] ef9118c

Description read

[DESCRIPTION-READ] c4807fdd3ba6fa82890475e24a06cb4be44aeeea24d8040bba78e5034bd65340

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level blocker: the four builders keep their output, the shape follows the merged RFC, and every type the PR adds has a caller.

Notes

  • The Stop path now runs the redactor on every click. Before, these four builders returned fixed dicts and could not fail; now they call render → display_safe_for(..., redactor=redact_via_context). If a loaded companion's pattern raises, or matches "Kill Now", the Stop or Kill Now card stops sending. A revert fixes this cleanly, but it is worth a test with a hostile companion pattern.
  • ident() refuses an empty action_id even under Fit.KEEP (required and not value → refuse=True). Today's constant ids make this unreachable, but it contradicts "a builder never raises where main returned blocks" for later cards whose action id is built from caller input.

[DESIGN-REVIEWED] ef9118c

Description read

[DESCRIPTION-READ] 5f3bb74c543f9f354892ab324b581d258ef769f733a141578dfc2bfee68d72cf

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 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ef9118c

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

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

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ef9118c

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

@kyleseaman
kyleseaman force-pushed the feat/card-catalog-phase-1 branch from a95c896 to 4c5b516 Compare November 12, 2026 18:31
@KiroCrewCaptain

KiroCrewCaptain commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 1199 lines, more than the 400 it may approve on its own.

Phase 1 of the channel card catalog RFC. Four constant-text Slack builders (stopping, stopped, stop-failed, working) now go through a new neutral render() that redacts, defuses mentions and checks Slack's size limits. I checked the claim that Slack sees no change against the code. The constant strings come out byte-identical after the bold rewrite and the escaping, which has nothing to replace. The session key goes into the ids and button value under Fit.KEEP, so it is never cut and never raises. Callers (events.py, commands.py, turn.py, interactions_sessions.py) are unchanged. The import-purity rules hold, and the claim that no security-posture row is needed matches the registry test, which treats redact_via_context as the answer rather than a finding. Golden snapshot tests for all variants plus thorough renderer tests (limits, redaction, structure, no remote media) back the change. No regression, data-loss or trust-boundary problem found.

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 64706f1ad0 · 1199 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 12, 2026
@kyleseaman
kyleseaman force-pushed the feat/card-catalog-phase-1 branch from 4c5b516 to 3ec83b1 Compare November 12, 2026 22:10
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 12, 2026
@kyleseaman
kyleseaman force-pushed the feat/card-catalog-phase-1 branch 2 times, most recently from 2fcc43f to 64706f1 Compare November 12, 2026 22:37
@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 Nov 12, 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.

Thanks. I read the whole diff on this head against the Phase 1 sign on the RFC (#34612): a card that posts today keeps today's behavior, and nothing gets stricter. That part holds:

  • The goldens pin all four builders, both working-card variants included, as equal dicts and as sorted-key JSON.
  • The session key, the only variable input, goes into the ids and the button value under Fit.KEEP. So a builder never raises where main returned blocks. test_a_builder_returns_main_payload_for_any_session_key covers an empty key and a key over every cap.
  • The RFC document edits stay inside the signed Phases 1 and 2. They narrow Phase 1 to what its four cards use, defer the other pieces to the phase that first needs them, and add Fit.KEEP to keep today's behavior on routing data. The posture row moving to the first phase that calls a redactor directly loosens nothing, because redaction still runs through display_safe_for.
  • No check is red. Some are still running.

One blocker: this project does not accept new regex in product code, and messaging/cards/render.py adds one:

_BOLD = re.compile(r"\*\*([^*\n]+?)\*\*")
...
safe = _BOLD.sub(r"*\1*", _escape(...))

Please replace it with plain string code and drop import re from render.py. For example, walk the string with str.find:

def _slack_bold(text: str) -> str:
    out, i = [], 0
    while (start := text.find("**", i)) >= 0:
        end = text.find("**", start + 2)
        inner = text[start + 2 : end] if end >= 0 else ""
        if not inner or "*" in inner or "\n" in inner:
            out.append(text[i : start + 1])
            i = start + 1
            continue
        out.append(f"{text[i:start]}*{inner}*")
        i = end + 2
    return "".join(out) + text[i:]

test_markdown_bold_becomes_slack_bold and the goldens should pass as written. The re uses in the two test files are fine. Everything else looks good to me, and I will approve once the regex is gone.

Kyle Seaman added 2 commits November 12, 2026 23:20
The four builders in slack/blocks.py, both working-card variants included,
as they render before moving onto card specs.
Adds kiro_crew.messaging.cards: a typed card spec (sections, context
lines, button rows) and one render() that joins and redacts each text
through display_safe_for with redact_via_context and the mention defuse,
escapes mrkdwn, checks Slack's own caps, and checks every emitted string
once more in the form it ships.

build_stopping_blocks, build_stopped_blocks, build_stop_failed_blocks and
build_working_blocks are now card specs. Their output equals the goldens.
@kyleseaman
kyleseaman force-pushed the feat/card-catalog-phase-1 branch from 64706f1 to ef9118c Compare November 12, 2026 23:27
@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 13, 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.

Approve. Thanks for the change. All checks are green.

I compared this head with 64706f1, the head I reviewed in full. The only changes are in render.py and its tests:

  • _BOLD = re.compile(...) and import re are gone. _slack_bold walks the string with str.find, and mrkdwn calls it in place of _BOLD.sub. No other regex is in the product files.
  • The new tests pin the regex's old behavior case by case (****, a newline inside, a * inside, an unclosed pair, ***a**, a lone **). test_render_holds_no_regex keeps re out of render.py.
  • The rest is unchanged from the head I read in full. The goldens pin all four Stop and working cards, the session key stays under Fit.KEEP so no builder raises where main returned blocks, and the RFC edits stay inside the signed Phases 1 and 2.

Phase 1 direction signed by maintainer (bolichen97) on #34612: existing card behavior unchanged and no added strictness. Phase 3 onward needs a separate sign-off.

@bolichen97
bolichen97 merged commit a6d0f72 into main Nov 13, 2026
97 checks passed
@bolichen97
bolichen97 deleted the feat/card-catalog-phase-1 branch November 13, 2026 01:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 13, 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