Repository navigation
docs: fix wrong pointers in core agent comments - #37415
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check: the change only edits comments. It takes nothing away and adds no user-visible surface. [DESIGN-REVIEWED] ee11c3d Description read[DESCRIPTION-READ] 5ab7f38b09c52f1a759119ba6065be259455d9a0db9a851df23820b8090ad223 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Every change is a comment, and every new name it cites exists in the code. What this change shipsInventory (9 items) — 9 justifiedIntent: make comments in the packages agents read most point at code that exists. This is a FIX.
[FIRST-PRINCIPLES-REVIEWED] ee11c3d Description read[DESCRIPTION-READ] b14130e425dd9faf786b9600de053a220841069d9b32a9288e3a29be90eb7f49 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Point comments in session, acp, crew_log, config and mcp_gateway at the functions and fields that exist: renamed readers, a moved helper, a counter's real name, the writers of a span, an option's real key. State two notes as current rules and turn a vague TODO into a scoped shortcut. Comments only; no code change.
e1aa13b to
ee11c3d
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved. What this review checked on head ee11c3d: every new pointer in the 12 files resolves to a real function, field or constant at this head. Examples are turn_boundary in kas_wire.py, _read_skip_permissions in sections_agent.py and the two span writers in projection_workstreams.py. Each changed file parses to an identical AST at the merge base and at the head, so no code or docstring changed. No test pins the old comment text, and PR Readiness is green.
Done well: where a name exists in both a facade and its owner module, the comment now cites the owner. History narration is replaced with present-tense statements of the invariant.
Optional:
- stub_register.py:56-58: the new
shortcut:note says to hash the fields "here" to split the pool. But pool.py deliberately ignoresconfig_snapshot_hashand has no config-snapshot dimension (see its module docstring). So the note could say a pool dimension in pool.py is also needed. - kas_wire.py:88: the old
observe_turnpointer was a forward reference to the open #25449. The new text is correct, and #25449 can add the consumer pointer when it lands.
Problem / Motivation
Goal: Make comments in the packages AI agents read most (
session,acp,crew_log,config,mcp_gateway) point at code that exists, so a reader who follows a comment's reference lands on the right function, field or key.Several comments in these packages name something that does not exist: a reader function that was renamed, a module a helper no longer lives in, a counter under a shorter name than its real one, a span writer that was split in two. An agent that follows such a pointer searches for nothing, or trusts a rule tied to the wrong code. This PR fixes those pointers, restates two notes as current rules, and turns one vague TODO into a scoped
shortcut:note. It changes no code.Why it matters
These are the files an agent opens first when it works on sessions, the ACP client, the crew log, config or the MCP gateway. A comment that names a missing function costs the reader a search and erodes trust in every other comment there; a correct pointer is the cheapest help a comment gives.
Not a goal
session.py), only the name it cites changes.What changed (motivation → approach → change)
Comments only, in 12 files (30 lines added, 27 removed). Each wrong reference was found by checking every name a comment cites against the code, then confirmed by hand.
config/resolution.py(2 sites)_read_dangerously_skip_permissions; the reader issections_agent._read_skip_permissionsacp/client_model_selection.py,acp/session_handle_class.pychat_runner._pinned_model_verdict/_native_subagent_syncinchat_runner; both live indashboard/chat_turn(model_fallback,native_cards)acp/kas_wire.pyAcpSessionHandle.observe_turn, which does not exist; the parser isturn_boundaryacp/runtime_class.py_result_at/_attempt_at; the fields are_entitlement_probe_result_at/_entitlement_probe_attempt_atcrew_log/projection_workstreams.py_workstreams_item_spanis the only writer; the writers are_workstreams_span_opened/_workstreams_span_closedcrew_log/projection_registry.pySLOT_FOLD_CACHE_BYTES; the budget isprojection_budget.DEFAULT_SLOT_FOLD_CACHE_BYTEScrew_log/read.pyactive_withinwindow; the option isactive_within_msmcp_gateway/backend.pyforward_id; the field is_forward_id_seqmcp_gateway/stub_register.pyshortcut:note saying what the placeholder costssession.py,acp/liveness_evidence.pyExamples:
acp/kas_wire.py-- a method that does not existBefore:
After:
acp/client_model_selection.py-- the helper lives elsewhereBefore:
After:
crew_log/projection_workstreams.py-- the writer was splitBefore:
After:
mcp_gateway/stub_register.py-- a vague TODOBefore:
After:
config/resolution.py-- a renamed readerBefore:
After:
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 astcheckagainst the merge-base: 12 files checked, 0 code-changed, 0 docstring-only.runtime_doc_check.py: 12 files, flagged 0.check_comment_history.py,check_brand_name.py,check_black_formatting.pyandcheck_harness_parity.pypass; flake8 is clean; no added line is over 100 columns.Manual verification
Each new name was checked to exist with
git grep -n "def <name>\|<name> ="before the edit.Related Issues
N/A — part of the src comment cleanup.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license.