Skip to content

docs: tighten whatsapp comments - #37330

Merged
iamwhatever merged 1 commit into
mainfrom
crew/testoptimizer/src-quality-whatsapp
Nov 14, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
crew/testoptimizer/src-quality-whatsapp

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make the whatsapp comments short, plain and true, so a reader (person or AI agent) gets each rule and its reason in fewer words.

Two comments in src/kiro_crew/whatsapp/ say the same thing twice: the session-store lock-down note in client.py repeats its own first paragraph, and the operator-authority note in transport.py restates step 3b a few lines above it. This PR merges those and shortens one more note. It changes no code.

Why it matters

Agents editing the WhatsApp channel read these comments to learn why a directory must be locked before pairing and when the operator counts as addressing the agent. Saying each fact once is easier to read and to keep true.

Not a goal

What changed (motivation → approach → change)

Comments only, in three files: client.py, transport.py, turn_renderer.py (14 lines added, 25 removed).

Where Kind of fix
client.py session-store lock-down duplicated: one paragraph instead of two that say the same
transport.py operator authority before the group gate duplicated: points to step 3b instead of restating it
turn_renderer.py redaction notice wordy

Examples:

  1. client.py, session store

    Before:

    # The session store IS the linked-device credential: anything that can
    # read it can act as the operator on WhatsApp. `os.chmod(0o700)` is a
    # silent no-op on Windows, so this goes through the shim that also sets
    # inheritable owner-only ACLs, and it fails loud rather than warn-and-continue.
    # FAIL LOUD, not warn-and-continue. This directory holds the linked-device
    # session, which IS the credential: anything that can read it can act as
    # the operator on WhatsApp, read every chat and send as them. Continuing
    # after the restriction failed would pair the device and leave that
    # credential readable by any other local principal, which is exactly the
    # case a warning nobody reads does not cover.
    # Off the loop: these are blocking filesystem calls (the Windows DACL is
    # applied in-process), and the one event loop also carries every other
    # channel and the liveness heartbeat. Still awaited rather than
    # fire-and-forget, because pairing must not begin until the credential's
    # directory is actually locked down.
    

    After:

    # The session store IS the linked-device credential: anything that can
    # read it can act as the operator on WhatsApp, read every chat and send
    # as them. `os.chmod(0o700)` is a silent no-op on Windows, so this goes
    # through the shim that also sets inheritable owner-only ACLs.
    # FAIL LOUD, not warn-and-continue: pairing after the restriction failed
    # would leave the credential readable by any other local principal.
    # Off the loop (blocking filesystem calls; the Windows DACL is applied
    # in-process) but awaited, so pairing starts only once the directory is
    # locked down.
    
  2. transport.py, operator authority

    Before:

    # ``from_me`` means the account sent it, which includes the operator
    # texting an ordinary contact from their phone. That is NOT a command: the
    # agent would answer their private conversation and reply into the
    # contact's chat. Operator authority in a DIRECT chat therefore requires
    # the self-chat, which is the command surface; in a configured group the
    # operator addresses the agent normally, gated by mention or rules.
    

    After (step 3b, ten lines above, already gives the reason):

    # Operator authority: in a DIRECT chat only the self-chat counts (see
    # 3b); in a configured group the operator addresses the agent normally,
    # gated by mention or rules.
    
  3. turn_renderer.py, redaction notice

    Before:

    # Post-answer redaction notice, counted over the converted chunks that
    # shipped (streamed prefix included — those are chunks[:start], already
    # delivered by earlier flushes). Best-effort by the shared contract:
    # ``_send`` raises so the dispatcher can fail an undelivered TURN, but
    # the answer is out by now, so the raise is contained here rather than
    # allowed to convert a delivered turn into a failed one.
    

    After:

    # Redaction notice, counted over the converted chunks that shipped
    # (including chunks[:start], streamed by earlier flushes). Best-effort:
    # ``_send`` raises so the dispatcher can fail an undelivered TURN, but
    # the answer is out, so the raise is caught here.
    

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: 3 files checked, 0 code-changed, 0 docstring-only.
  • runtime_doc_check.py: 3 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.

Merge two comments that each said the same thing twice (session store
lock-down in client, operator authority in transport) and shorten the
redaction-notice note. Comments only; no code change.
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 14, 2026 19:53
@iamwhatever
iamwhatever enabled auto-merge (squash) November 14, 2026 19:54
@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 594c2e069304ef2adf4b3be61dcbb885c0bcd9c9 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

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 594c2e069304ef2adf4b3be61dcbb885c0bcd9c9 — 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

This PR changes comments only. Nothing new is added, so nothing has to justify its existence.

Notes

  • Item 1 — undeclared: the PR says "no fact is dropped", but it deletes the reason the work runs off the event loop: "the one event loop also carries every other channel and the liveness heartbeat". The remaining "Off the loop (blocking filesystem calls…)" no longer says why blocking the loop would matter.

What this change ships

Inventory (3 items) — 2 justified

Intent: make the WhatsApp channel comments say each rule and its reason once, in fewer words. This is a FIX (docs).

  1. client.py session-store note: two repeated paragraphs become one — undeclared: the reason the work runs off the event loop is deleted
  2. transport.py operator-authority note now points to step 3b, which already gives the reason — justified
  3. turn_renderer.py redaction-notice note is shorter — justified

[FIRST-PRINCIPLES-REVIEWED] 594c2e0

Description read

[DESCRIPTION-READ] 011cab312c308f55f786cdf505a87e6552c4bbbb3ea214c5324b806c079165f8

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

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Comment-only change with no code impact. Each fact that was removed is still stated in the merged comment or in step 3b.

[DESIGN-REVIEWED] 594c2e0

Description read

[DESCRIPTION-READ] 5e9b9d98eb4de54778d54a6e492c2661e7ddda1ec5fde28b1c09d4f6f9a998ff

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

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 594c2e0

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 594c2e069304ef2adf4b3be61dcbb885c0bcd9c9 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 594c2e069304ef2adf4b3be61dcbb885c0bcd9c9 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 594c2e0

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 594c2e069304ef2adf4b3be61dcbb885c0bcd9c9 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.

Approved. This head changes only comments in whatsapp/client.py, transport.py and turn_renderer.py. The review found the parsed AST of all three files identical at the merge-base and at this head, so behaviour cannot change. The review also checked each new comment against the code. _restrict_session_store still raises on failure and is awaited through asyncio.to_thread before pairing. The "see 3b" pointer leads to the full from_me reasoning. The redaction notice send is wrapped in try/except. The source-reading test in test_whatsapp_client.py still finds its line.
Done well: each rationale you removed still exists one hop away, and the from_me rule now has one source instead of two copies that could drift.
Optional:

  • client.py:286: the merged comment no longer says why a blocking call on the loop hurts (the single loop also carries every channel and the heartbeat). A short phrase such as "Off the shared loop" would bring that back.

@iamwhatever
iamwhatever merged commit d422369 into main Nov 14, 2026
100 of 101 checks passed
@iamwhatever
iamwhatever deleted the crew/testoptimizer/src-quality-whatsapp branch November 14, 2026 21:47
@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