Skip to content

build(ui-index): drop the digest and count lines that every UI change edited - #37406

Merged
buluoray merged 1 commit into
mainfrom
crew/slack/ui-index-no-volatile-header
Nov 15, 2026
Merged

buluoray merged 1 commit into
mainfrom
crew/slack/ui-index-no-volatile-header

Conversation

@buluoray

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Two PRs that change dashboard UI on different pages can both merge without one of them rebasing for src/kiro_crew/docs/ui-index.generated.json.

The generated find_ui index starts with two lines that change on almost every UI change, whatever page it touches: input_digest (a hash of the whole index) and the coverage line (a count of locations per kind). So two PRs that touch unrelated pages still edit the same two lines, and git reports a conflict. On 2026-11-14, main changed the file 8 times in 24 hours and 39 times in 7 days, and 10 of the 12 open PRs that change it were conflicting.

Why it matters

Every such conflict means a rebase, a regenerated file, a push and a full CI restart (about an hour). A rebase also gives the PR a new head, so any review sign-off or override recorded for the old head no longer counts. By the time CI is green again, main has often changed the file again. Release-branch backport PRs hit the same conflict.

Not a goal

  • Splitting the index into several files, or no longer committing it.
  • Changing how strict the freshness check is, or what the index contains for find_ui and guides.
  • Avoiding conflicts when two PRs change the same page or the same index entry; those are real conflicts.

What changed (motivation → approach → change)

The two lines change because they summarize the whole file. Neither has to live in it:

  • input_digest is only read to check that the build-time auto tier was built from this index. The file no longer carries it. The generator stamps the auto tier with sha256 of the exact text it writes, and the Python reader computes the same hash from the file it reads (parse_index_text in ui_index_load.py, used by load_index and guide_catalog.ui_auto_tier). Python's text read turns CRLF into LF, so a Windows checkout gets the same hash. A file that still names a digest keeps it.
  • The per-kind counts, tier counts and registered-control count had no reader outside the generator's own summary and --report. buildUiIndex now returns them as stats, and the committed coverage keeps only its fixed scope text.

build_digest stays in the file: it covers only guide plans and observable ids, and changed in none of the 39 commits.

The two docs that described the digest are updated.

Backwards compatibility

Compatible: the freshness check still compares the whole file byte for byte, and every reader of the removed keys now gets them from the code path listed below.

Reader: src/kiro_crew/ui_index_load.py:_attach_auto -- chat -- input_digest comes from parse_index_text in load_index; test_find_ui_browse.py auto-tier tests and test_find_ui_auto.py::test_the_generated_auto_tier_is_well_formed
Reader: src/kiro_crew/ui_index.py:_envelope -- chat -- reads idx.raw["input_digest"], which load_index fills in; test_find_ui.py
Reader: src/kiro_crew/guide_catalog.py:ui_auto_tier -- chat -- reads the base index through parse_index_text; test_guide_observe.py::test_an_auto_location_is_observed_through_its_stamped_site
Reader: website/scripts/gen-ui-index.mjs:summary and writeReport -- release -- read counts and tiers from built.stats / autoBuilt.stats; npm run gen:ui output unchanged
Reader: website/src/uiLocations/autoTier.test.ts -- release -- asserts on stats and on the committed file's coverage holding only scope

Tests

  • test_the_committed_index_digest_is_computed_from_its_text (new): the digest is sha256 of the text, a CRLF file gives the same digest, a file that names one keeps it, and the committed file has no input_digest.
  • autoTier.test.ts (new case): the committed file has no input_digest and its coverage holds only scope. Existing count assertions now read stats.
  • test_the_generated_auto_tier_is_well_formed runs the real generator and checks the auto tier's base_input_digest equals the digest the reader computes.
  • Ran: 8 related Python test files (603 passed; the one failure, continue with github, fails the same way on main and is test_find_ui_auto: the Continue with GitHub golden fails wherever the generator runs #32670), the 3 uiLocations vitest files (190 passed), gen-ui-index.mjs --check, flake8, isort, black, mypy, eslint, tsc -p tsconfig.app.json, the flake-pattern ratchet and the repo's semgrep rules (0 findings).

Manual verification

A simulation with two real main commits that changed UI on different pages: #37050 (Notifications settings) and #29423 (Security settings). Both start from #37050's parent, each with its source change applied and npm run gen:ui run.

Generator git merge-tree --write-tree A B
today's exit 1, CONFLICT (content): Merge conflict in src/kiro_crew/docs/ui-index.generated.json
this PR's exit 0, clean

With this PR, gen-ui-index.mjs --check also passes on the merged tree with no regeneration: the merge of the two generated files equals what the generator writes for the merged source.

Related Issues

Closes #37396

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

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 14, 2026 23:23
@buluoray
buluoray requested a review from Zedmor November 14, 2026 23:23
@buluoray
buluoray enabled auto-merge (squash) November 14, 2026 23:23
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 14, 2026
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check: the diff only touches build scripts, the generated index, Python loaders, tests and docs, and adds or changes no user-visible control.

[UX-REVIEWED] 6711548

Description read

[DESCRIPTION-READ] a73178c71a1eefa6cdadc3b132315d75112d5a2d4cd631dca588264264cc421d

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 67115486be3ffc9caca5f3b3f6b108ade27b22df — 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

One rider: the branch that keeps a file's own input_digest exists only for test fixtures.

Notes

  • Item 6 — zero consumers: "A file that still names a digest keeps it." The generator no longer writes input_digest, and the only non-test callers of parse_index_text are load_index and ui_auto_tier, which both read the committed file. Grepping "input_digest": finds only fixtures (test_find_ui.py:632, test_find_ui_auto.py:107, test_guide_ui_show_auto.py:75, test_find_ui_browse.py:487/547). Subtraction: delete the "input_digest" not in raw guard in ui_index_load.py:parse_index_text and always compute the digest. Fixtures then build their digest from their own text.

What this change ships

Inventory (7 items) — 6 justified

Intent: let two PRs that change UI on different dashboard pages merge without a forced rebase of the generated find_ui index. FIX (#37396, with a measured conflict rate and a merge-tree reproduction).

  1. The committed index no longer has an input_digest line — justified
  2. The committed coverage keeps only scope; counts, tiers and the registered-control count are gone — justified
  3. The reader computes the index digest as sha256 of the file's text (parse_index_text, 2 production callers) — justified
  4. buildUiIndex drops its inputDigest input and returns stats instead (1 consumer: gen-ui-index.mjs) — justified
  5. The auto tier's base_input_digest is now a hash of the written bytes, not the canonical JSON — justified
  6. A file that carries its own input_digest keeps it — zero consumers (only fixtures use it)
  7. Two docs now describe the digest the reader computes — justified

[FIRST-PRINCIPLES-REVIEWED] 6711548

Description read

[DESCRIPTION-READ] b0b3fb9f521178063d4cd125377e60039225743f66b81367c6955dfcf044ab58

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns. I checked every reader of the removed input_digest and coverage.counts/tiers/registered_controls keys against the tree: _envelope, load_index, ui_auto_tier, the generator's summary and report, and .github/scripts/ui_index_freshness.py, which compares the file byte for byte. All of them still work.

Notes

  • The comment added in website/scripts/lib/ui-index.mjs names index_input_digest in ui_index_load.py, but the function there is parse_index_text, so the pointer leads nowhere.

[DESIGN-REVIEWED] 6711548

Description read

[DESCRIPTION-READ] c4cb337e309348207010e45488dce131db9115ef34db5dd9079ea6f032eb48dd

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

Notes:

  • The comment at website/scripts/lib/ui-index.mjs:781 names index_input_digest, but the reader function is parse_index_text.

[OPUS-REVIEWED] 6711548

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

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

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6711548

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

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@buluoray
buluoray force-pushed the crew/slack/ui-index-no-volatile-header branch from 022d68a to 40d5023 Compare November 15, 2026 00:17
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

Removes input_digest and the per-kind counts from the committed ui-index so unrelated UI PRs stop conflicting. The generator now stamps the auto tier with sha256 of the exact serialized string it writes (gen-ui-index.mjs:404-410), and Python computes the same value with parse_index_text, used by load_index, _attach_auto and guide_catalog.ui_auto_tier. .gitattributes forces eol=lf, and JSON escapes CR inside strings, so the hashes agree across platforms. I swept src/, .github/, the scripts and the website tests for input_digest and coverage.counts/tiers/registered_controls readers: none remain beyond the generator's summary and report, which now read built.stats/autoBuilt.stats. Fixtures that carry an explicit input_digest keep it. Under --warn-if-stale, a stale committed file still refuses the auto tier, as before, and any edit to the committed file now breaks the match, which makes the trust check slightly stricter. The facade TYPE_CHECKING list is updated, and the frozen base-name inventory isn't affected. New Python and vitest tests pin the behaviour.

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

@buluoray
buluoray force-pushed the crew/slack/ui-index-no-volatile-header branch from 40d5023 to 6711548 Compare November 15, 2026 00:59
@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 15, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

The review checked head 6711548 and found nothing that blocks. The generator now hashes the exact text it writes. parse_index_text recomputes the same digest from the file, a CRLF checkout included. All three readers of input_digest (_attach_auto, _envelope, ui_auto_tier) still get a value. A search of src, website, scripts and .github found no remaining reader of coverage.counts, coverage.tiers or registered_controls. Each moved reader has a test that goes red if its hunk is reverted, and the end-to-end test that runs the real generator fails rather than skips in CI.

Done well: the body backs its claims with measurements, including a git merge-tree run over two real main commits, and its Reader list names the test that covers each removed key.

Optional:

  • build_digest did change in 7 of the 39 commits the body counts (for example 176820c and a02e90c). Two PRs that both change guide plans, or both add a condition or gate, still conflict on those summary rows. The new sentence in docs/ci/ci-and-reviews.md around line 754 could say so.
  • website/scripts/lib/ui-index.mjs:781 names index_input_digest, which does not exist. The function is parse_index_text.
  • The branch in ui_index_load.py:75 that keeps a file's own input_digest is reached only by test fixtures. You could drop it later if the fixtures compute their own digest.

@buluoray
buluoray merged commit 6f4a30b into main Nov 15, 2026
153 of 156 checks passed
@buluoray
buluoray deleted the crew/slack/ui-index-no-volatile-header branch November 15, 2026 02:59
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 2026
buluoray added a commit that referenced this pull request Nov 15, 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.

ci: ui-index.generated.json conflicts most open UI PRs every day

2 participants