Skip to content

docs(agent_sdk): shorten long comments and docstrings - #31643

Merged
iamwhatever merged 2 commits into
mainfrom
crew/testoptimizer/src-agent-sdk-wordy
Nov 7, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
crew/testoptimizer/src-agent-sdk-wordy

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make the harness membership comments in agent_sdk/backends_turns.py, agent_sdk/backends_mcp.py and agent_sdk/backends_routing.py shorter and easier to read, with no code change.

Several membership comments take 30 to 110 lines to say which harnesses belong to a set and why. They repeat the same point, retell how a conclusion was reached, and keep superseded measurements next to the committed fixture that replaced them.

Why it matters

These sets decide how Crew steers, compacts, routes MCP settings and gates tool approval per harness. A reader who has to work through 100 lines of narrative to find the rule is more likely to misread it.

Not a goal

  • No change to any set's members, any function, or any runtime-read string.
  • No edits to backends.py, backends_members.py, agent_specs.py, tool_gate.py or host_auth.py.
  • backends_models.py and backends_sessions.py are left for a later pass.

What changed (motivation → approach → change)

Each comment keeps its rule, the reason for it, and the evidence (version, fixture path, the observed result). What goes: repeated statements, narration of how the conclusion was reached, and numbers that a committed fixture now covers.

File Comment blocks tightened
backends_turns.py ACP_BACKENDS_STEER, ACP_BACKENDS_STEERING_REQUEST, ACP_BACKENDS_COMPACT, ACP_BACKENDS_HARNESS_MANAGED_COMPACTION, ACP_BACKENDS_CONTEXT_RECYCLE, ACP_BACKENDS_INLINE_COMPACTION
backends_mcp.py ACP_BACKENDS_EFFORT_OVERLAY, ACP_BACKENDS_CLIENT_META_SETTINGS
backends_routing.py ACP_BACKENDS_SIDE_READONLY (one bullet per member, the later per-harness paragraphs folded in), ACP_BACKENDS_META_IDENTITY, ACP_BACKENDS_PERMISSION_KIND_FROM_TOOL_CALL, ACP_BACKENDS_HOST_AUTH_CALLBACK, and the SEEDED_SETTINGS, VERIFIED_SEEDED_SETTINGS and VERIFIED_GATE_EXTENSION entries of the Routing docstring

comment_scan.py lines --root src/kiro_crew --pkg agent_sdk: 8896 -> 8712 comment lines. goal_scan.py astcheck <merge-base>: files checked: 3 code-changed: 0 docstring-only: 1. The one docstring touched is Routing's, which nothing reads at runtime (no __doc__ or getdoc use). The Captured on dsh 0.2.0-rc.2 with line that test_acp_deepseek_backend_session.py reads from the source is kept on one line.

Backwards compatibility

Compatible: comments and one docstring only; the AST of all three files is otherwise unchanged.

Removes nothing: no code, key, record or function is touched.

Tests

Proof: not provable -- docs or config only

After a rebase on main, the 297 test files that name agent_sdk (pytest -n 4): 15,926 passed, 101 failed. The same 101 fail on origin/main on this host (the copilot tool-gate refusal and PlatformCompositionError in test_acp_* files), so they are not from this change. flake8, the brand gate and scripts/check_comment_history.py pass on the changed files.

Manual verification

N/A — comment-only change, checked with astcheck, flake8, scripts/check_comment_history.py and a 100-column check on added lines.

Screenshots / video

N/A — no frontend file is touched.

Related Issues

N/A

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

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 6, 2026 18:23
@iamwhatever
iamwhatever requested a review from Zedmor November 6, 2026 18:23
@iamwhatever
iamwhatever enabled auto-merge (squash) November 6, 2026 18:23
@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) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 7b8c609

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

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

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing to check. Only comments and one docstring change. Each block keeps its rule, its reason and its evidence pointer, and the source line the deepseek test reads is still intact.

[DESIGN-REVIEWED] 7b8c609

Description read

[DESCRIPTION-READ] e52a30847b22f23a423e85a15fc9b3ba2d328e5db370b6ddd3173bac1c06c808

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

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 7b8c609ca02fb4062cb6ba1d72f679d52189196d — 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 to check.

What this change ships

Inventory (4 items) — 4 justified

Intent: make the harness-membership comments in three agent_sdk files faster to read without changing behaviour. This is an ADDITION (a docs tightening), not a fix.

  1. The steer and compaction set comments in backends_turns.py are shorter — justified
  2. The effort-overlay and client-meta set comments in backends_mcp.py are shorter — justified
  3. The ACP_BACKENDS_SIDE_READONLY comment and other routing set comments in backends_routing.py are shorter, one bullet per member — justified
  4. The Routing docstring entries are shorter and now point to the existing Readback class — justified

[FIRST-PRINCIPLES-REVIEWED] 7b8c609

Description read

[DESCRIPTION-READ] 8cbeffe972e8255ad0c544f15fe06017af54d9713246e5e98e7ac2b9c57638c5

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

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7b8c609

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 7b8c609ca02fb4062cb6ba1d72f679d52189196d 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 6, 2026
@iamwhatever
iamwhatever disabled auto-merge November 6, 2026 20:13
@iamwhatever
iamwhatever force-pushed the crew/testoptimizer/src-agent-sdk-wordy branch from 116c378 to d168727 Compare November 6, 2026 20:51
@iamwhatever
iamwhatever enabled auto-merge (squash) November 6, 2026 20:51
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased on main to pick up #31625 (security line-budget test fix for shard 2). New head d168727. astcheck code-changed 0, runtime_doc_check flagged 0, comment-history and brand gates passed. 298 agent_sdk test files: 15,980 passed, 100 failed; the same 100 fail on origin/main on this host.

@iamwhatever
iamwhatever disabled auto-merge November 6, 2026 22:05
@iamwhatever
iamwhatever enabled auto-merge (squash) November 6, 2026 22:05
@iamwhatever
iamwhatever force-pushed the crew/testoptimizer/src-agent-sdk-wordy branch from d168727 to 7b8c609 Compare November 6, 2026 22:05
@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

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving head 7b8c609. The gate showed 94 checks passed. The three red ones, PR Readiness, Sensitive Change Review and Dependency License Gate, failed on the GitHub API rate limit, and their reruns passed.

This is comments and docstrings only. I parsed each of the 3 changed agent_sdk backend files at the merge base and at this head, removed docstrings, and compared the ASTs. All 3 are identical, so no code changed.

@iamwhatever
iamwhatever merged commit 5fbb5fd into main Nov 7, 2026
153 of 159 checks passed
@iamwhatever
iamwhatever deleted the crew/testoptimizer/src-agent-sdk-wordy branch November 7, 2026 11:14
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 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