Skip to content

chore(src): drop history comments in non-app subpackages, part 1 - #24500

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
chore/src-comments-subpackages-part1
Oct 26, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
chore/src-comments-subpackages-part1

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Remove PR-history narration from # comments in the non-app subpackages of src/kiro_crew/, with no behaviour change, as part 1 of the last step of the source-comment rollout piloted in #23966 (slack/).

With dashboard/, the top-level modules and the builtin apps done or in review, the remaining history comments are spread thinly over many subpackages, so this PR takes them in one pass instead of one PR per two-line package. The comments narrate the branch that wrote them instead of the rule: "the bug this change exists to fix", "the one artifact this PR exists to produce", "GPT's prescribed remedy was ... Declined", "(GPT review r23)", "an earlier draft of this entry", "how an earlier revision leaked slots", "exactly as before this feature existed". AGENTS.md and the worktree-dev skill say comments state current behaviour and the non-obvious why, with no review rounds or task log.

Why it matters

"This change" and "this PR" stop meaning anything once the PR merges, and a review tag tells a reader who asked, not why the code is right.

Not a goal

  • No docstring edits.
  • No code, behaviour, or formatting change.
  • No edits to governance, grant, tool-gate, credential, redaction or risk-gating code (list below).
  • Packages already covered by their own PR (slack/, dashboard/, top-level modules, apps/).

What changed (motivation → approach → change)

17 files in 13 subpackages touched. Only # comment lines changed.

lines
Comment lines with history narration rewritten 51 -> 45
Net comment lines removed 6
Non-comment lines touched 0

Subpackages: agent_parts, apple_speech, autonudge_service, config, crew_log, discord, knowledge, llm_helpers_parts, mcp_gateway, mcp_tools, monitoring, subagent_manager, vector_memory_runtime.

Every rewrite states the rule, not its history. Before pushing I checked the added lines for anything over 100 columns and for leftover "this change", "this PR", "earlier revision", round, GPT, Opus or "before this feature" wording; there is none.

Examples, one per kind

1. Review-round tag (apple_speech/__init__.py)

-                # WAV and exhaust the temp volume (GPT review r23). This is the
+                # WAV and exhaust the temp volume. This is the

2. "This change exists to" (agent_parts/spec_lookup.py)

-            # and refusing it would leave a live pin unresettable, which is the
-            # bug this change exists to fix. Only used when no declared match is
-            # found, and a declared match alongside it is the ambiguity the
+            # and refusing it would leave a live pin unresettable. Only used when
+            # no declared match is found, and a declared match alongside it is the
+            # ambiguity the

3. Review proposal, kept as the decision (autonudge_service/gate.py)

-            # GPT's prescribed remedy was to revert this counter until it could be
-            # charged after delivery. Declined: the counter is what separates a
-            # quiet verdict from a free tick, so deleting it would remove the
-            # subtraction that makes the metering honest. The substance -- charge
-            # only on confirmed delivery -- is adopted instead, by the mechanism
-            # the wake charge already uses.
+            # The counter stays rather than being reverted until it can be charged
+            # after delivery: it is what separates a quiet verdict from a free
+            # tick, so deleting it would remove the subtraction that makes the
+            # metering honest. It is charged only on confirmed delivery, by the
+            # mechanism the wake charge already uses.

4. "An earlier draft" narration, kept as the rule (crew_log/projection_dashboard.py)

-    # presence of ``corrects``: an earlier draft branched on the list and gave a
-    # correction no code at all, which the append validator refused outright -- so
-    # every correction was dropped at the door and the book stayed a list of errors
-    # with no answers in it.
+    # presence of ``corrects``: branching on the list would give a correction no
+    # code at all, which the append validator refuses outright -- so every
+    # correction would be dropped at the door and the book would stay a list of
+    # errors with no answers in it.

5. "Before this feature" (subagent_manager/run_turn.py)

-                    # before surfacing (empty chain ⇒ raise exactly as
-                    # before this feature). Two attempts per candidate
+                    # before surfacing (empty chain ⇒ raise directly).
+                    # Two attempts per candidate

What was kept, and why

  • "earlier versions" of kiro-cli in acp/runtime_reader_loop.py and "an earlier version" of an installed store in whatsapp/client.py: old releases the code still meets.
  • "backwards compatibility with an earlier draft" of SEP-1865 in mcp_gateway/apps.py: an external spec draft the code still reads.
  • Opus as an audio codec (telegram, whatsapp, doctor_checks, apple_speech) and model ids in validation_parts / agent_sdk/backends_models.py.
  • Where unsure, the comment stayed.

Skipped security files

Not edited, even where they carry history comments: agent_sdk/backends.py (governance ceilings), agent_sdk/tool_gate.py, agent_parts/spec_grants.py, agent_parts/spec_rebuild.py (ceiling-filtered installer), agent_materialization/fork_refresh.py (grants), diag/procs.py (credential redaction), mcp_gateway/rewriter_launch.py (spec-controlled fields), decisions/points/tool_risk.py, pod/runtime_home.py (SSO tokens), messaging/dispatch_admission.py. They get their own reviewed pass.

Backwards compatibility

Compatible: only comments change; every touched file has the same AST as its base.

Removes nothing: no code, key, record, validator or public function changes.

Tests

Proof: not provable -- copy-only change

AST-identical proof. goal_scan.py astcheck <merge-base> compares ast.dump(ast.parse(src)) for every .py file changed against the merge base (9d51fb4db0); docstring-only differences would be reported separately and there are none:

files checked: 17  code-changed: 0  docstring-only: 0

Gates on the touched files:

  • flake8, isort --check-only: clean
  • black: scripts/check_black_formatting.py passes
  • mypy: Success: no issues found in 17 source files
  • check_comment_history.py and check_brand_name.py: pass
  • Related tests (297 test/test_*<module>*.py files for the touched modules, KIROCREW_PROFILE=standalone pytest -n 4): 10781 passed, 49 skipped, 23 failed. All 23 are in test_pi_gate_extension_steer.py and test_pi_gate_extension_mcp.py and fail with mise ERROR error parsing config file from this host's tool-version manager; none touches a changed module.

Manual verification

N/A — comment-only change; the AST check proves the compiled code is unchanged.

Related Issues

None.

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 October 26, 2026 17:19
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 26, 2026
@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 29b6b696a76c08adbb20f91265a15760c2227ef0 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 Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 29b6b696a76c08adbb20f91265a15760c2227ef0 — 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. Every changed line in the patch is a # comment, and AGENTS.md's comment-history rule requires exactly this cleanup.

What this change ships

Inventory (3 items) — 3 justified

Intent: make source comments in 13 non-app subpackages describe current behaviour instead of PR or review history. This is a FIX, a cleanup that AGENTS.md mandates.

  1. History wording ("this change exists to", "GPT review r23", "an earlier draft", "before this feature") removed from 17 files' comments — justified
  2. Review-round decisions (for example the autonudge counter in gate.py) restated as the rule they now enforce — justified
  3. Six comment lines removed in net; no code, docstring or formatting line changed — justified

[FIRST-PRINCIPLES-REVIEWED] 29b6b69

Description read

[DESCRIPTION-READ] b55204e77f1c40d4dd1e1789b2093fa1f6e2e382c93e5787671eabf28a9a73af

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 Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing to check. Every line the patch adds or removes is a # comment, so no behaviour changes and nothing is taken away.

[DESIGN-REVIEWED] 29b6b69

Description read

[DESCRIPTION-READ] 1b9fe842eca6fc15166aa1d526916ceea22b508b27d9c8ba2695b74b03c29f80

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 Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 29b6b69

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

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

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 29b6b69

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

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Backend Tests (3.12, 2/4) and Windows (2/4) red at 30c49dd. Shard 2: the three stale strict xfails fixed by #24485 (merged after this head was cut). Shard 4: test_telegram_dispatcher.py::TestABusyReplyCarriesItsContext (2 tests), red on clean main too, tracked as #24514. This PR changes only comments (17 files, AST-identical) and touches no telegram code. I will rebase once #24514 is fixed.

@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 Oct 26, 2026
Rewrite "this change exists to fix", "this PR exists to produce",
"an earlier revision/draft", "GPT review rN" and similar narration in
`#` comments across agent_parts, apple_speech, autonudge_service,
config, crew_log, discord, knowledge, llm_helpers_parts, mcp_gateway,
mcp_tools, monitoring, subagent_manager and vector_memory_runtime as
the rule each one carries. Comments only: every touched file has the
same AST as its base. Governance, grant, tool-gate, credential and
redaction code is left for its own reviewed pass.
@iamwhatever
iamwhatever force-pushed the chore/src-comments-subpackages-part1 branch from 30c49dd to 29b6b69 Compare October 26, 2026 20:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 26, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto main to pick up #24485 (stale strict xfails, shard 2) and #24531 (dbf207c, telegram shard 4, #24514). New head 29b6b69, same patch (astcheck against the merge base: 17 files, 0 code changed; comment-history and brand gates pass).

@iamwhatever

Copy link
Copy Markdown
Contributor Author

macOS (3) red: teardown errors in test_crew_log_types.py ("a lease outlived its test"), leaked by the dispatch-view guard in test_crew_log_fullscan_guard.py. That is tracked in #24526 and is not this diff (comments only). macOS is non-blocking, so I am leaving it.

@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 Oct 26, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 26, 2026 23:05

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

Tier 1 auto-approve: chore (17 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: comment-only edits that drop change-history wording from source comments; no code line changes.

@KiroCrewCaptain
KiroCrewCaptain merged commit b225188 into main Oct 26, 2026
111 of 112 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the chore/src-comments-subpackages-part1 branch October 26, 2026 23:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 26, 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