Skip to content

docs: fix wrong pointers in core agent comments - #37415

Merged
iamwhatever merged 1 commit into
mainfrom
crew/testoptimizer/src-deep-agent-core
Nov 15, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
crew/testoptimizer/src-deep-agent-core

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

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

  • No code change: the AST of every changed file is identical (proof below).
  • No docstring is touched.
  • No new comments that restate code.
  • No security reasoning is changed; where a pointer sat inside a security note (the Kiro account check in 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.

Where What was wrong
config/resolution.py (2 sites) cited _read_dangerously_skip_permissions; the reader is sections_agent._read_skip_permissions
acp/client_model_selection.py, acp/session_handle_class.py cited chat_runner._pinned_model_verdict / _native_subagent_sync in chat_runner; both live in dashboard/chat_turn (model_fallback, native_cards)
acp/kas_wire.py cited AcpSessionHandle.observe_turn, which does not exist; the parser is turn_boundary
acp/runtime_class.py named the probe clocks _result_at / _attempt_at; the fields are _entitlement_probe_result_at / _entitlement_probe_attempt_at
crew_log/projection_workstreams.py said _workstreams_item_span is the only writer; the writers are _workstreams_span_opened / _workstreams_span_closed
crew_log/projection_registry.py cited SLOT_FOLD_CACHE_BYTES; the budget is projection_budget.DEFAULT_SLOT_FOLD_CACHE_BYTES
crew_log/read.py cited an active_within window; the option is active_within_ms
mcp_gateway/backend.py described forward_id; the field is _forward_id_seq
mcp_gateway/stub_register.py vague "in a future iteration" TODO; now a shortcut: note saying what the placeholder costs
session.py, acp/liveness_evidence.py history wording ("pre-stamping status quo", "as they did before it existed", "reaped a live turn") stated as current rules

Examples:

  1. acp/kas_wire.py -- a method that does not exist

    Before:

    # are the only start and end it has (``AcpSessionHandle.observe_turn``).
    

    After:

    # are the only start and end it has (parsed by :func:`turn_boundary`).
    
  2. acp/client_model_selection.py -- the helper lives elsewhere

    Before:

    # display verdict uses (chat_runner._pinned_model_verdict), so the
    

    After:

    # display verdict uses (chat_turn.model_fallback._pinned_model_verdict), so the
    
  3. crew_log/projection_workstreams.py -- the writer was split

    Before:

    # monotonic watermark does. ``_workstreams_item_span`` is the only writer.
    

    After:

    # monotonic watermark does. ``_workstreams_span_opened`` and
    # ``_workstreams_span_closed`` are the only writers.
    
  4. mcp_gateway/stub_register.py -- a vague TODO

    Before:

    # TODO: Hash relevant config fields (e.g. tool allowlists,
    # hook settings) in a future iteration to detect non-security config drift
    # that could cause subtle behavioral differences across pooled sessions.
    

    After:

    # shortcut: the snapshot is a fixed placeholder, so pooled sessions whose tool
    # allowlists or hook settings differ share one backend; hash those fields here
    # once such non-security drift needs to split the pool.
    
  5. config/resolution.py -- a renamed reader

    Before:

    # unattended auto-approval. See sections._read_dangerously_skip_permissions.
    

    After:

    # unattended auto-approval. See sections_agent._read_skip_permissions.
    

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: 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.py and check_harness_parity.py pass; 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

  • 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.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 14, 2026 23:48
@iamwhatever
iamwhatever requested a review from buluoray November 14, 2026 23:48
@iamwhatever
iamwhatever enabled auto-merge (squash) November 14, 2026 23:48
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 14, 2026
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision ee11c3def86c420db25d5c9410c45467d94344ed 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 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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 .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 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ee11c3def86c420db25d5c9410c45467d94344ed — 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. Every change is a comment, and every new name it cites exists in the code.

What this change ships

Inventory (9 items) — 9 justified

Intent: make comments in the packages agents read most point at code that exists. This is a FIX.

  1. The config renamed-key comments point at sections_agent._read_skip_permissions — justified
  2. The ACP comments point at the chat_turn helpers _pinned_model_verdict and _native_subagent_sync — justified
  3. The kas_wire turn-frame comment points at turn_boundary — justified
  4. The runtime probe-clock comment uses the full field names — justified
  5. The crew-log comments name the split span writers, the full budget constant and active_within_ms — justified
  6. The mcp_gateway/backend.py comment names _forward_id_seq — justified
  7. The stub_register.py TODO is now a shortcut: note — justified
  8. In the session.py identity note, the account check now points at account_identity — justified
  9. The session.py cache-stamp and session_parts comments were reworded from history to current state — justified

[FIRST-PRINCIPLES-REVIEWED] ee11c3d

Description read

[DESCRIPTION-READ] b14130e425dd9faf786b9600de053a220841069d9b32a9288e3a29be90eb7f49

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ee11c3d

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

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

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ee11c3d

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ee11c3def86c420db25d5c9410c45467d94344ed 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 15, 2026
@iamwhatever
iamwhatever disabled auto-merge November 15, 2026 01:05
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.
@iamwhatever
iamwhatever force-pushed the crew/testoptimizer/src-deep-agent-core branch from e1aa13b to ee11c3d Compare November 15, 2026 01:05
@iamwhatever
iamwhatever enabled auto-merge (squash) November 15, 2026 01: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 15, 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. 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 ignores config_snapshot_hash and 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_turn pointer was a forward reference to the open #25449. The new text is correct, and #25449 can add the consumer pointer when it lands.

@iamwhatever
iamwhatever merged commit 2092903 into main Nov 15, 2026
99 checks passed
@iamwhatever
iamwhatever deleted the crew/testoptimizer/src-deep-agent-core branch November 15, 2026 02:21
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 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