Skip to content

docs: tighten metrics, session_parts and channel comments - #37333

Merged
iamwhatever merged 2 commits into
mainfrom
crew/testoptimizer/src-quality-metrics-session
Nov 14, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
crew/testoptimizer/src-quality-metrics-session

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make comments in metrics, session_parts and six channel/member files short, plain and true, so a reader (person or AI agent) gets each rule and its reason in fewer words.

Several comments in these files take eight to twenty-three lines for a few facts, two describe history instead of the current rule, and one Teams note sits far from the argument it explains. This PR rewrites those comments. It changes no code.

Why it matters

Agents editing telemetry, session state and the channel dispatchers read these comments to learn why an import is lazy, a lease stays armed or a field is chosen. A shorter comment that states the current rule is easier to act on and to keep true.

Not a goal

  • No code change: the AST of every changed file is identical (proof below).
  • No docstring is touched.
  • No new comments that restate code.
  • Security notes are left as they are (member-records leaf, token host checks, SSRF vet, approval and context-withholding notes).

What changed (motivation → approach → change)

Comments only, in nine files (77 lines added, 106 removed), in two commits: one for files other open PRs also touch, one for metrics and session_parts.

Where Kind of fix
metrics/provider.py lazy SDK import, embed buckets, reader reap, install id wordy; the embed note told history ("predate this map", "old scan")
metrics/events.py webhook counter wordy
session_parts/record.py replay lease hard to read, one line over 100 columns
session_parts/policy.py drain timeout named a past incident; now states the rule
members_parts/member_space.py legacy activity file wordy
teams/transport_dispatch.py moved the conversation_id note onto that argument; split a glued note
teams/client.py, webex/transport_dispatch.py, whatsapp/renderer.py wordy

Examples:

  1. metrics/provider.py, embed buckets (history)

    Before:

    # Embedding queue wait + inference time. Both are ms and both predate this
    # map; neither name ends in `.duration`, which is precisely why the guard
    # test's old name-suffix scan could not see them and they have been running
    # on OTEL's default 0..10000 boundaries. The guard now finds histograms by
    # reading their emit calls, so they are registered here. ...
    

    After:

    # Embedding queue wait + inference time, both ms. Neither name ends in
    # `.duration`; the guard test finds histograms by their emit calls, not by
    # name. _FAST_BUCKETS_MS because a warm local embed is single-digit ms and
    # a cold model load or a long batch reaches seconds.
    
  2. session_parts/policy.py, drain timeout (history)

    Before:

    # This is the co-operative drain the empty-response-after-Make-Live incident
    # needed; the subsequent SIGTERM grace (AcpRuntime 5s / AcpClient 3s) is what
    # then lets kiro-cli release its native-session lock.
    

    After:

    # Without this drain a Make-Live cutover can leave a turn with an empty
    # response; the SIGTERM grace that follows (AcpRuntime 5s / AcpClient 3s) lets
    # kiro-cli release its native-session lock.
    
  3. metrics/provider.py, reader reap

    Before:

    # PeriodicExportingMetricReader starts its daemon ticker thread inside
    # __init__, so if any later step (MeterProvider construction, etc.) raises,
    # the reader is already ticking. This list is bound BEFORE the try — binding
    # it inside would leave it unbound when the first reader's constructor
    # raises, and the except would then fail on the reap instead of degrading —
    # and each reader joins it once constructed, so the except reaps every one.
    # Otherwise an orphaned thread keeps running and spamming export WARNINGs for
    # the life of the process even though metrics are "disabled".
    

    After:

    # PeriodicExportingMetricReader starts its ticker thread in __init__, so a
    # later raise (e.g. in MeterProvider) leaves it running and logging export
    # WARNINGs forever while metrics read as "disabled". Each reader joins this
    # list once built, and the except reaps them all. Bound BEFORE the try so
    # the except can still read it when the first constructor raises.
    
  4. teams/transport_dispatch.py, misplaced note

    Before (above _surface_new_session, 30 lines from the argument):

    # ... ChannelTurn.conversation_id is the SESSION-attribution id
    # (``teams:{email}``), not ``inbound.conversation_id`` -- the platform id the
    # renderer replies into. Passing the platform id would repoint every existing
    # Teams session.
    

    After (on the argument itself):

    # The SESSION-attribution id, not ``inbound.conversation_id``
    # (the platform id the renderer replies into), which would
    # repoint every existing Teams session.
    conversation_id=f"teams:{email}",
    

Backwards compatibility

Compatible: comments only; the AST of every changed file is unchanged.

Removes nothing: no code, test, docstring or check is removed.

Tests

Proof: not provable -- comment-only change; the AST check below shows no code moved.

  • goal_scan.py astcheck against the merge-base: 9 files checked, 0 code-changed, 0 docstring-only.
  • runtime_doc_check.py: 9 files, flagged 0.
  • check_comment_history.py and check_brand_name.py pass on the added lines; flake8 and black are clean; no added line is over 100 columns.

Manual verification

N/A — comment-only change.

Related Issues

N/A — part of the src comment cleanup.

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.

zejiangg added 2 commits November 14, 2026 19:56
Shorten wordy comments in member_space, the Webex and Teams
dispatchers, the Teams client and the WhatsApp renderer, and move one
misplaced Teams note onto the argument it explains. Comments only; no
code change.
Shorten wordy comments in metrics provider and events and in
session_parts record and policy, and state two notes as current rules
instead of their history. Comments only; no code change.
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 14, 2026 19:57
@iamwhatever
iamwhatever enabled auto-merge (squash) November 14, 2026 19:58
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 14, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 7ae122227900ec9d2a2b7992ab775e573cc00914 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The patch only changes comments, and the comment move in teams/transport_dispatch.py keeps the conversation_id note's meaning.

[DESIGN-REVIEWED] 7ae1222

Description read

[DESCRIPTION-READ] d2c622935ab764ba70adddf17aa1eaa5829f16270d0ba6924aa2f50b73aff06f

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 7ae122227900ec9d2a2b7992ab775e573cc00914 — 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. Only comments change, no code or default moves, and no comment that warned against a change was weakened or reversed.

What this change ships

Inventory (7 items) — 7 justified

Intent: make comments in the metrics, session-state and channel files shorter and accurate, so a reader gets each rule and its reason quickly. This is a FIX, to the comments only.

  1. Metrics provider comments are shorter (lazy SDK import, embed buckets, reader reap, install id), and the embed note no longer tells history — justified
  2. The webhook counter comment is shorter but still says "neither is redundant" — justified
  3. The replay-lease comment in session record is re-wrapped under 100 columns — justified
  4. The drain-timeout comment now states the rule, not the past incident — justified
  5. The legacy activity-file comment is shorter — justified
  6. The Teams conversation_id note moved onto its argument, and a run-together note was split in two — justified
  7. Comments on Teams byte ceiling, Webex collapse and WhatsApp stable split are shorter — justified

[FIRST-PRINCIPLES-REVIEWED] 7ae1222

Description read

[DESCRIPTION-READ] afed70f9310d28f5c2ae97f6ea3e28da3992a5fb51f1df6899ff590c0d963eab

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 7ae1222

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

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

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7ae1222

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

@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 14, 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.

Approving. On this head, the review parsed all 9 changed files at the merge-base and at 7ae1222 and found the Python AST identical in every file, so this changes comments only. No added line is over 100 columns. No test pins the removed wording. The details the rewrite drops (the WhatsApp completing-span note, the Make-Live drain incident) are still documented in the turn renderer and the session spec.
Done well: the Teams session-attribution warning now sits on the exact conversation_id=f"teams:{email}" argument it guards, and the metrics comments now state the current rule instead of narrating history.

  • Optional: in members_parts/member_space.py, "nothing grows it" sits next to "the file stays agent-writable". "No Kiro Crew writer grows it" would remove that tension.
  • Optional: in teams/client.py, "webhook / card limit" can read as covering bot cards too. "Incoming-Webhook / message-extension card limit" keeps the original distinction.
  • Optional: #37183 edits metrics/provider.py just above the reader comment, so whichever lands second may need a small rebase.

@KiroCrewCaptain KiroCrewCaptain mentioned this pull request Nov 14, 2026
5 tasks done
@iamwhatever
iamwhatever merged commit 054844a into main Nov 14, 2026
98 checks passed
@iamwhatever
iamwhatever deleted the crew/testoptimizer/src-quality-metrics-session branch November 14, 2026 21:48
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 14, 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.

2 participants