Skip to content

docs: describe the first-load pinned-order seed accurately - #31411

Merged
bolichen97 merged 1 commit into
mainfrom
fix/22182-pinned-seed-contract
Nov 6, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/22182-pinned-seed-contract

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make the pinned-order comments and the agent-facing pin-move text describe what the sidebar actually does on first load.

The pinned-order contract in website/src/utils/pinnedSessionOrder.ts says pinned rows stay unranked until someone reorders, so the pinned section keeps its plain sort. In the list view that is not what happens: the sidebar's first load saves the order it is showing (only_if_unset), so every pinned row gets a pin_rank without anyone reordering, and a later pin appends instead of sorting in. Other comments, and the chat_session_pin_move tool description, repeat the same claim.

Why it matters

The docstring reads as the contract for pinned ordering. Anyone changing the sidebar or the gateway route from that text would expect unranked rows that are in fact ranked, and could "fix" the intended seed or build on behaviour that does not exist. An agent reading the tool description is told the wrong order for rows nobody dragged.

Not a goal

What changed (motivation → approach → change)

The text promised a plain sort the sidebar does not keep. The first-load seed is deliberate: its own comment says so, and the ChatSidebar.hapticTaps and ChatSidebar.slotSearchOrder tests name it. So the text is what is wrong, and only text changes.

Where What it says now
utils/pinnedSessionOrder.ts contract the first load seeds an order (the old local order if kept, then the natural order); the plain sort holds only while no order is saved: a board view with no old local order, an empty roster, or until the seed succeeds
chat-sidebar/pinnedOrder.ts, api/client/chatOrganization.ts the seed ranks rows nobody reordered; it sends the old local order then the natural order; a board view seeds when it kept an old local order; a failed seed is sent again on the next sidebar mount
dashboard/chat_folders.py, dashboard/pinned_session_order.py, state_parts/dashboard_state.py, state_parts/sidebar_stores.py, test_pinned_session_order.py "never reordered" and "a browser's old local order" become "no order saved" and "the first-load seed"
mcp_dashboard.py, mcp_dashboard_folder_tree.py, docs/session-control.md rows with no stored position follow most-recent activity, instead of rows "the person never reordered"
docs/system-specs/modules/learn-cron-dashboard.md the seed sends the old local order then the natural order; a board view with no old local order sends nothing

Backwards compatibility

Compatible: only comments, docstrings, one test docstring, one tool description sentence and doc prose change; no code path, route, or stored format is touched.

Removes nothing: the diff edits prose only.

Tests

No tests added: no behaviour changes. The one test edit rewords the docstring of test_pin_into_an_unused_order_keeps_it_empty; its assertion is unchanged. Ran:

  • pytest -n 4 on test_pinned_session_order.py, test_pinned_order_real_sandbox.py, test_chat_folders_facade.py, test_mcp_dashboard_pin_move.py, test_mcp_dashboard_registration.py, test_session_control_doc.py, test_session_control_member_gate.py, test_session_control_audit.py: 239 passed
  • vitest run on ChatSidebar.hapticTaps, ChatSidebar.slotSearchOrder, pinnedSessionOrder: 21 passed
  • tsc -p tsconfig.app.json, eslint on the three TS files; black, isort, flake8, mypy on the touched Python files; test_flake_pattern_ratchet.py, check_comment_history.py, check_brand_name.py, check_file_line_cap.py, docs-lint.sh, semgrep on the diff: all pass

Manual verification

N/A — comments and description text only, no runtime behaviour to exercise.

Screenshots / video

Why no screenshot: comments only under website/src/, so nothing renders differently.

Related Issues

Closes #22182

Builds on #22936 by @mbriones98.

Follow-up: #25075 (deferred seed change, option 2 in #22182)

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

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 12:31
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 12:31
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check. The diff only changes comments, docstrings, docs and one tool-description sentence. No website line outside a comment is touched, so no user-visible control is added or changed and no screenshot is needed.

[UX-REVIEWED] 457f606

Description read

[DESCRIPTION-READ] 66671f19a1e31118b22eae731699e0a734251db62270d14a1f846fa7504b915c

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 457f606a30cd3c4e335f4b902ae0c8e27f9410e4 — 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

Prose only. The comments that said "never reordered" now match the first-load seed at pinnedOrder.ts:216 ([...legacy, ...naturalPinnedOrder]). No code, default or surface changes.

What this change ships

Inventory (6 items) — 6 justified

Intent: make the pinned-order contract comments and the agent tool text describe the sidebar's real first-load seed. FIX (docs).

  1. utils/pinnedSessionOrder.ts contract now says the first load seeds an order, and the plain sort holds only while no order is saved — justified
  2. Sidebar and client comments (pinnedOrder.ts, chatOrganization.ts) say the seed sends the old order "then" the natural order, and that a failed seed is resent on the next mount — justified
  3. Gateway docstrings and comments (chat_folders.py, pinned_session_order.py, dashboard_state.py, sidebar_stores.py) change "never reordered" / "hand-off" to "no order saved" / "seed" — justified
  4. The chat_session_pin_move tool description an agent reads changes "rows the person never reordered" to "rows with no stored position" — justified
  5. session-control.md gets the same rewording — justified
  6. The spec learn-cron-dashboard.md changes "or else" to "then", and the board-view sentence to "sends nothing" — justified

[FIRST-PRINCIPLES-REVIEWED] 457f606

Description read

[DESCRIPTION-READ] 8b5f69f36364c0a226cbacd692e8e49b638da3e8c502bd459fc16416ba37b090

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Only comments, docstrings and one tool description sentence change, and they now match the first-load seed the code and tests already have. Nothing to check.

[DESIGN-REVIEWED] 457f606

Description read

[DESCRIPTION-READ] 6ee97eda7891bd59172bbc30a857723f74332f01b15c81e89400750ab25c20c0

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 457f606

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

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

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 457f606

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 12:43
@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 6, 2026
@bolichen97
bolichen97 force-pushed the fix/22182-pinned-seed-contract branch from cda48c6 to 88f8270 Compare November 6, 2026 15:07
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/learn-cron-dashboard.md (same file) and 71 files beside or imported by this diff since this head went green (090dad8 -> 85ce466); CI re-running. The diff is unchanged.

[operator: bolichen97]

@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: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 6, 2026
The pinned-order contract said a person who never reordered keeps the
plain sort inside the pinned section. The sidebar's first list-view
load seeds an order with only_if_unset (this browser's old local order
if it kept one, then the natural order), so rows gain a pin_rank
without any reorder and later pins append. The seed is intended, so
the text is corrected wherever it repeated the claim: the contract
docstring, the seed hook and client notes, the route and store
docstrings, the agent-facing pin-move description and session-control
doc, and the owning spec. No code changes.

Builds on #22936.

Co-authored-by: Matthew Briones <50031759+mbriones98@users.noreply.github.com>
@bolichen97
bolichen97 force-pushed the fix/22182-pinned-seed-contract branch from 88f8270 to 457f606 Compare November 6, 2026 16:12
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in 17 files beside or imported by this diff since this head's CI ran (85ce466 -> 89a6107); CI re-running. The diff is unchanged. The backend shard that failed was main's own security package line-budget test, which main raised in #31469; the two AI review lanes failed on a rate limit before reviewing.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 6, 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.

Approved by Crew Captain for the on-call: checks green, PR Readiness passed, review lanes clean on this head.

@bolichen97
bolichen97 merged commit a49dd0c into main Nov 6, 2026
98 checks passed
@bolichen97
bolichen97 deleted the fix/22182-pinned-seed-contract branch November 6, 2026 17:42
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 6, 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.

sidebar: the first-load pinned-order seed ranks rows nobody reordered

2 participants