Skip to content

feat(warm-brief): check facts first and draw one card per pr or task - #30767

Closed
iamwhatever wants to merge 1 commit into
mainfrom
feat/warm-welcome-v3
Closed

iamwhatever wants to merge 1 commit into
mainfrom
feat/warm-welcome-v3

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When the owner returns to a busy thread, the welcome states what the gateway just checked, so a conflicting PR or a failed check is always shown, and each ask appears once, with its own answers, on the card it belongs to.

The 16:47Z welcome on 2026-11-05 ("Crew Mate Harness Provider Support") read GitHub at 16:47 and saw both PRs conflicting with 3 failed checks each. Yet it said "#29509 is blocked waiting for your approval on two tool calls the chat made at 11:17", and the conflict showed only in a footnote. The top of the card held raw worker reports cut with "…", including "Could not read GitHub" from before the 16:47 read. The same four options were drawn four times under one ask, though they belonged to three different things. In zh the footnote showed the raw English words "review required · conflicting".

Why it matters

The welcome is the first thing the owner reads on return. When it contradicts a fresh read, the owner acts on stale words. That means approving or restarting work that first needs a rebase, and missing failed checks. Raw worker reports and repeated asks make the card slow to scan and easy to misread.

Not a goal

What changed (motivation → approach → change)

Root causes, read at origin/main before this PR:

  1. Lines were checked for ids, not claims. typed_lines kept a line when its fact ids existed, never comparing the sentence with the fact's values.
  2. Times passed if they appeared anywhere in the snapshot. _unbacked_facts accepted any HH:MM in the grounding text, not only a check time.
  3. Casing. The GitHub provider returns lower-case values (conflicting, review_required), but both word maps keyed on upper case. Both maps were also keyed by value alone, so a PR's blocked mergeability got the task word.
  4. Worker reports stood beside facts as equals. Raw report text became the yellow cards, and the conductor's free [OPTIONS:] line was copied under one ask.

Approach (design: warm-welcome-v3/report.md sections 1–3; the owner accepted all eight recommendations):

  • Fact registry (dashboard/warm_task_brief_registry.py). One checker per kind runs before the model call:

    • pr: the live read, as before.
    • task
    • waits_on_you: the board's own awaits_person, so the welcome and the board agree.
    • chat: running / interrupted / idle / closed. interrupted is the sidebar's own test.
    • approval: per worker slot.
    • ask: the goal-board asks entry per item, then waiting question and change cards. The free [OPTIONS:] line is not a source.
    • file: os.stat only, at most 10 artifact paths, inside the workspace root, never a sensitive path.
    • time

    Each fact is marked bad when it is a conflict, a failed check, requested changes, a closed worker chat on an open task, or a waiting approval. Closed tasks and remote workers ask nothing. A worker report older than a read of the item's own PR is superseded by that read. A wake check's file facts are preferred over stat-only ones (prefer_wake_files).

  • Claim check (dashboard/warm_task_brief_claims.py). Each bad value forbids a short, fixed phrase list stating its opposite, in all seven fixed-line languages: an exact lookup, not an open text scan (owner Q2). A sentence that contradicts a fact on its card is dropped.

  • Cards (dashboard/warm_task_brief_cards.py, components/chat/WarmBriefCards.tsx). There is one card per work item that needs attention, per PR no item holds, and per waiting question or change card.

    • Gateway parts, in the brief's language: titles, PR pills (the dot turns red when any tag is bad), tags, one check line, the status label, and one muted "older report replaced by the HH:MM check" line (Q6).
    • The model adds one sentence, which must cite facts on its card. A sentence citing none is shown as "Worker says:".
    • The model adds one ask. Its options come only from that subject's ask fact (Q3): a goal-board asks entry counts only while the item still waits on the person. There is one ask per subject, and a closed task keeps none.
    • The ask's answers are drawn as plain text: each option, its consequence, and the recommended one starred.
    • The headline must cite a bad fact when one exists. Otherwise the gateway writes it.
  • Buttons split out. Card answer buttons moved to a follow-up PR, which will fill an answer together with the item it answers. Local review blocked the button hand-off on different grounds four times, so this PR ships text only.

  • Chip bar kept as the click path. Whenever the last conductor turn had an [OPTIONS:] line, the welcome copies today's chip bar unchanged. With the card buttons gone, it is the one-click answer.

  • Time rule. An HH:MM must be the "as of" time or a time a fact carries (RFC 3.9.6 as written).

  • Casing. Both word maps are per field and lower case. The legacy card still reads older upper-case rows.

  • Dashboard. with_worker_facts stamps each open goal-board item with its cached PR facts and that read's own time, only while the item still holds the PR that was read. The goal-board draws the same conflict, failed-check and review tags. Chat and approval state are never shown from the cache, and nothing is read from the network on page load.

  • warm_task_brief.py stays under the 2,000-line cap: the prompt moved to dashboard/warm_task_brief_prompt.py.

This is a product-shape change to the welcome. Its RFC amendment (section 3.10 of docs/request-for-change/rfc-delayed-task-brief.md) is in a companion docs PR, so First Principles may block until that merges.

Backwards compatibility

Compatible: rows stored before this PR keep their old shape and still draw with the legacy card. Only new welcomes write meta.brief.version: 3. The PR-number, SHA and secret scans are unchanged.

The diff also takes one thing away: the tighter time rule. The welcome rejects an HH:MM that appears only in the transcript or the change list.

Reader: src/kiro_crew/dashboard/warm_task_brief.py:_unbacked_facts -- chat -- the prompt now names the allowed times; test_a_time_only_the_snapshot_holds_fails_the_check
Reader: src/kiro_crew/dashboard/member_waiting.py:pending_options -- chat -- still read and copied on every welcome; test_a_note_in_the_live_window_wins_over_the_settled_disk_read, test_a_card_that_asks_keeps_the_chip_bar
Reader: website/src/components/chat/WarmBriefCard.tsx:warmBriefOf -- chat -- older rows keep the legacy render; the existing warmTaskBrief.test.tsx cases

Tests

  • test/test_warm_task_brief_v3.py (new) covers:
    • The real 16:47Z row: both cards carry "有冲突" and "3 项检查失败" as bad tags, the headline cites the conflict, the older report is marked replaced at 16:47, and 11:17 is now a grounding miss.
    • Lower-case value mapping, and a PR's blocked kept apart from a task's.
    • Ask options landing only on their own card, and only while the item waits; a closed task keeps no ask.
    • The claim check, and the headline fallback.
    • The registry: bad facts, closed and remote items, approvals, the file stat scope, the wake preference, chat interrupted, no red tag for a closed chat after a done report.
    • A skipped task leaves its PR its own card.
    • The board stamp: the PR's own read time, never an unread or replaced PR, no chat or approval.
  • Updated existing warm brief tests for the v3 shape, the kept chip bar and the time rule.
  • website/src/test/warmTaskBrief.test.tsx covers per-field casing; the v3 card (tags, check line, no old sections, PR pill URL check); answers as text with no button; and ErrorNotice for a failed read.

Proof: not provable -- other: a feature PR, not a fix; prove.py reverts fix hunks only

Manual verification

  • Rendered the card from the real 16:47Z facts through the dashboard's own components at 320px and full width, in light and dark (screenshots below).
  • Not checked against a live gateway on a running thread.

Screenshots / video

Before (today's card on the real 16:47Z row):

before, full width, light

After (same 16:47Z facts; answers as text, the chip bar below the row is unchanged):

after, full width, light

after, 320px, dark

A PR that could not be read (dashed pill, "not checked" tag, error notice):

unread PR, full width, light

The goal-board with the same PR tags and their read time:

goal-board, light

goal-board, dark

The other widths and themes

before, 320px, light
before, 320px, dark
before, full width, dark
after, 320px, light
after, full width, dark

The "after" model sentences are written in the owner's language from the row's own words; the option labels are the conductor's own. The row stored no chat liveness, so there are no chat tags.

Related Issues

Refs #30527 (wake turn: its proven file, deploy and ticket checks join this fact table as one more source).

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.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 5, 2026 20:51
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the PR fixes the root causes it names (claims checked against fact values, times checked against check times, word maps lower-cased per field), and the one thing it takes away is listed with a test.

Notes

  • warm_task_brief.py is now exactly 2,000 lines, so even after the prompt moved out, the next added line breaks the cap. AGENTS.md wants a split once a file passes 1,600 lines, so move another whole responsibility (for example the grounding and time checks) into its own module now.
  • The claim check is a fixed list of opposite phrases in seven languages. Any other wording of a contradiction gets through. The owner accepted this as Q2, so it is a choice, but the headline-must-cite-a-bad-fact rule and the gateway-written tags are what actually keep a conflict visible. Keep that ordering in the spec so later reviews don't grow the phrase list.

[DESIGN-REVIEWED] d01bffa

Description read

[DESCRIPTION-READ] 5c22e8947bc7df7183acf28a7e6bdf62fa4c91db34ef6837d28bbb5308dbd48a

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d01bffaa155fe38833c1a6ce92f189c09a51a04d — 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. The base RFC rfc-delayed-task-brief.md (status partial) already contains the 2026-11-05 section 3.10 amendment as not-yet-built design, and that amendment covers every product-shape item here.

Notes

  • Item 9 — rides along: "Chip bar kept as the click path" sits next to an extra goal-board-only English word list (fact_conflicts, fact_review, …) in goal-board/template.html. These are a third spelling of tags that warm_task_brief_cards.WORDS already holds, but each surface has its own catalog, so it is inventory, not a defect. Subtraction: none that fits inside the goal-board's self-contained template.

What this change ships

Inventory (10 items) — 10 justified

Intent: when the owner returns to a busy thread, the welcome states freshly checked facts (conflicts, failed checks) and shows each ask once, on its own card. A FIX plus a redesign; RFC §3.10 covers both.

  1. The welcome gathers facts from one registry (PR, task, waits-on-you, chat state, approval, ask, file stat, time) before the model writes — justified
  2. A model sentence that contradicts a fact on its card is dropped, using an exact per-value phrase lookup — justified
  3. One card per PR, task or waiting question, with gateway tags; bad tags always shown — justified
  4. Each ask's options appear only on its own card, as plain text, taken only from goal-board asks — justified
  5. An older worker report shows as "replaced by the HH:MM check" — justified
  6. An HH:MM must be the "as of" time or a fact's time, so a time found anywhere in the snapshot no longer passes — justified
  7. zh and other locales get their own words for lower-case GitHub values; a PR's blocked is kept apart from a task's — justified
  8. Goal-board shows conflict, failed-check and review tags with their read time, from the cache only — justified
  9. The chip bar stays the click path; card buttons are deferred — justified
  10. The prompt moves to warm_task_brief_prompt.py to stay under the line cap — justified

[FIRST-PRINCIPLES-REVIEWED] d01bffa

Description read

[DESCRIPTION-READ] f14461e274035318df7feb18f3ffb1ad74aa95fbad302c772dda45fc66165997

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

No blocker: the screenshots cover every new card state, the blind reader read the PR pill correctly, and the answer lists are plain text by design.

Notes

  • In WarmBriefCards.tsx, the answers inside Answers (★ I'm here, restart…, Hold the fix…) look like choices but can't be clicked. The blind reader said: "I would not know how to choose." Until the button PR lands, add one muted line under the list that points to the reply chips below the card.
  • Shot-04: the headline still says "两个 harness PR 都有冲突" (both PRs have conflicts) next to "feat(crew): pick a crewmate's agent harness from the runnable list #29498 未核实" (feat(crew): pick a crewmate's agent harness from the runnable list #29498 not verified). When a PR in the headline wasn't read, fall back to the headline the gateway writes.
  • Shot-04: the failed-read notice keeps the footnote mark "²", but the v3 card has no footnotes. Remove the mark from factText when the brief is v3.

[UX-REVIEWED] d01bffa

Description read

[DESCRIPTION-READ] bafdc668040464a925490c5262571979dcfb3f6598f33303faca5bf98ed78437

That sha256 names everything this verdict read: the PR description, plus the 14 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 5, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — 🔴 changes requested (blocking)

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

When the ledger changes while the brief is being written, the fallback welcome still draws its task, waiting-on-you and ask cards from the snapshot taken before the change, so the owner sees work-item states that are already out of date.

BLOCKING — src/kiro_crew/dashboard/warm_task_brief.py:1891
newer = cards_mod.cleaned(await registry.gather(found, facts.MAX_FACTS), _clean) (where found = _fact_inputs(state, slot, fresh, ...), line 1872) / registry.on_loop_again(newer, _fact_inputs(state, slot, settled, anchor, live))
Trigger: A worker reports done/blocked, or an item's question is answered, during the model or wake call, so settled.ledger_digest != fresh.ledger_digest. That takes the changed branch. on_loop_again re-reads only the chat, approval and source == "waiting" facts. It keeps every task, waits_on_you and goal-board ask fact from newer, which was gathered over fresh.work_items. Then _post_changed → cards_mod.apply → build draws the cards from those kept facts.
Outcome: The welcome that is posted because the ledger moved still shows the old state. An answered item can still read "has a question", carry a "waits on you" tag with its old goal-board options, and push the status to needs_you. A newly done or blocked item shows its earlier state. This breaks the spec's promise (session.md:220) that this path draws the re-read's own waiting items.
Anchor: defect
Fix: In the changed branch, rebuild the off-loop task, waits and ask facts from settled.work_items. If no await is allowed between the re-read and the post, do it with a sync rebuild, or with one more gather over _fact_inputs(state, slot, settled, …) before the final _settled re-read. Do not keep them from newer.

[BLOCK-MERGE] d01bffa
[OPUS-REVIEWED] d01bffa

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

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

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging d01bffaa155fe38833c1a6ce92f189c09a51a04d. Adjudication upheld 1 of 1 blocking finding(s); those must be resolved before merging.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/dashboard/warm_task_brief.py:1891 -- Changed-state fallback retains obsolete task and ask facts

registry.on_loop_again(newer, _fact_inputs(state, slot, settled, anchor, live)), _clean
Trigger: A conductor closes a question/blocked item during _generate. The subsequent gather still uses fresh.work_items; _settled detects the changed ledger, but on_loop_again preserves the old task, wait and goal-board ask facts.
Outcome: _post_changed publishes the terminal item as “has a question” and “waits on you,” retaining its answer options and a needs_you status.
Anchor: defect
Fix: Rebuild ledger-dependent facts from the settled items before rendering the fallback, or omit affected cards when those facts cannot be refreshed safely.
Sites: src/kiro_crew/dashboard/warm_task_brief.py:1872 gathers obsolete items; src/kiro_crew/dashboard/warm_task_brief_registry.py:403 preserves their facts; src/kiro_crew/dashboard/warm_task_brief_cards.py:294 builds cards from them; src/kiro_crew/dashboard/warm_task_brief.py:1973 publishes that retained table.

[BLOCK-MERGE] d01bffa
[GPT-REVIEWED] d01bffa

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1: MEDIUM. This is wrong output on the very path that exists to keep the post truthful. Confirmed in code:

  • newer is built from found, which reads the earlier snapshot's fresh.work_items (warm_task_brief.py:1871-1873).
  • Task, wait and ask facts are computed in the background thread, so on_loop_again keeps them unchanged; it only re-reads chat, approval and waiting facts (warm_task_brief_registry.py:322, 402-407).
  • _post_changed then records facts_digest from settled, so the next return hits the "unchanged" skip and the stale card is never corrected (warm_task_brief.py:1965, 1854-1855). Recovery: none.

The real fix is cheap: in on_loop_again, drop or re-state the kept task, wait and ask facts against the settled items. It needs no new await and no new mechanism, so the harm outweighs the cost.

[ADJUDICATION] d01bffaa155fe38833c1a6ce92f189c09a51a04d total=1 uphold=1 downgrade=0
UPHOLD F1 src/kiro_crew/dashboard/warm_task_brief.py:1891 reason=harm-warrants-remedy
[GPT-ADJUDICATED] d01bffaa155fe38833c1a6ce92f189c09a51a04d

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

@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 Nov 5, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 5, 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 6, 2026
@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 Nov 6, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running 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: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 6, 2026
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 6, 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 6, 2026
@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 6, 2026
The 16:47Z welcome read GitHub at 16:47 and saw both PRs conflicting
with 3 failed checks, yet said "blocked waiting for your approval at
11:17": lines were checked for fact ids, not for what they said, times
passed when they appeared anywhere in the snapshot, lower-case provider
values missed both word maps, and worker summaries stood beside the
facts as yellow cards with the same asks drawn four times.

A fact registry now runs one checker per kind before the model call
(PR, task, waits on you, worker chat, approvals, goal-board asks,
artifact stats, time); worker reports become hints that a newer PR read
supersedes. The gateway builds one card per PR or task with its own
tags in the brief's language, keeps a model sentence only when it
contradicts no fact on its card, makes the headline cite a bad fact or
uses its own, takes each ask's options from that subject's ask fact
only, and accepts an HH:MM only when a fact carries it. The board
stamps the same facts from the in-memory cache, with no network read.
@github-actions github-actions Bot added readiness: checking Automated validation is still running 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: 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 Nov 6, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Superseded by #33032, which carries the surviving parts of this change (fact registry, Board PR tags, casing and time fixes) in the owner-directed one-PR redesign. Closing per owner decision 2026-11-09.

@iamwhatever iamwhatever closed this Nov 9, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant