Skip to content

chore(apps): drop history and restating comments - #24642

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
chore/src-comments-apps-core
Oct 27, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
chore/src-comments-apps-core

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Remove PR-history narration from # comments in the app platform core (src/kiro_crew/apps/ outside builtins/), with no behaviour change, as part of the source-comment rollout piloted in #23966 (slack/).

The builtin apps were cleaned in their own PRs; this is the app platform around them. Its comments narrate how the code was reached instead of the rule: "three review rounds found three different unbounded fields", "three reviewer findings were three exits from the same mistake", "four review rounds landed here", "this catch is what hid the KeyError above for four review rounds", "two opposite review findings about this exact line", "does not belong in this change". 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

A count of review rounds tells a reader how long a fix took, not what the code guards, and "this change" stops meaning anything once the PR merges.

Not a goal

  • No docstring edits (the docstring hits in registry_pipeline/recovery.py, bridges_agents.py and job_sdk_returns.py stay).
  • No code, behaviour, or formatting change.
  • No edits to apps/builtins/, which had their own PRs.

What changed (motivation → approach → change)

5 files touched. Only # comment lines changed.

lines
Comment lines with history narration rewritten 26 -> 22
Net comment lines removed 4
Non-comment lines touched 0

Files: plugin_import.py, registry_pipeline/checkout.py, registry_pipeline/install.py, routes_uninstall.py, teardown.py.

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 count, kept as the rule (plugin_import.py)

-    # read. Three review rounds found three different unbounded fields in this
-    # same structure -- mcpServers, then the carried block and keywords, then
-    # displayName and description -- because a per-field bound only ever covers
-    # the fields someone remembered, and every one of them is foreign text this
+    # read. A per-field bound only ever covers the fields someone remembered
+    # (mcpServers, the carried block, keywords, displayName, description all
+    # live in this one structure), and every one of them is foreign text this

2. "Earlier drafts" narration, kept as the invariant (registry_pipeline/checkout.py)

-    # Destination lifecycle, stated as one invariant because three reviewer findings
-    # were three exits from the same mistake:
+    # Destination lifecycle, stated as one invariant:
 ...
-    # The earlier drafts put cleanup on each failure branch, so each fix closed one
-    # exit and left the others: adopting a non-checkout destination (deleted the
-    # user's files), a moved-aside restore that skipped on cancellation, and finally
-    # a spawn exception between `git init` and `git remote add` that left a `.git`
+    # Cleanup on each failure branch leaves the other exits open: adopting a
+    # non-checkout destination (deletes the user's files), a moved-aside restore
+    # skipped on cancellation, or a spawn exception between `git init` and
+    # `git remote add` that leaves a `.git` directory with no origin -- which then

3. A bug's history, kept as the reason for the log level (registry_pipeline/install.py)

-                # WARNING, not debug: this catch is what hid the KeyError above for
-                # four review rounds. A restoration that could not run is a possible
-                # data loss, so it has to be visible in the log the user sees.
+                # WARNING, not debug: a quiet catch here hides errors like the KeyError
+                # above. A restoration that could not run is a possible data loss, so
+                # it has to be visible in the log the user sees.

4. "This change" (routes_uninstall.py)

-        # `mcp_discover.py`) — the lock has no neutral home yet, and giving it one
-        # is a ~15-file refactor that does not belong in this change.
+        # `mcp_discover.py`) — the lock has no neutral home yet; giving it one
+        # is a ~15-file refactor of its own.

What was kept, and why

  • teardown.py: the two opposed risks (a) and (b) and the reason (b) wins stay word for word; only "two opposite review findings" became "two opposite risks".
  • "legacy" registry names, keep_data, notification kinds and config writers in routes_registry.py, routes_art.py, routes_uninstall.py, routes_enable.py and update_notify.py: old data the code still reads.
  • "previous checkout" in registry_pipeline/install_*.py: the moved-aside checkout, a runtime object.
  • Where unsure, the comment stayed.

Skipped security files

None in this package carried a history comment. dashboard/chat_tag_grants.py and skills_body_reads.py still do and stay out of scope (grants and sensitive body reads).

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 (96c4fef57c); docstring-only differences would be reported separately and there are none:

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

Gates on the touched files:

  • flake8, isort --check-only: clean
  • black: scripts/check_black_formatting.py passes (teardown.py is on the existing baseline)
  • mypy: Success: no issues found in 5 source files
  • check_comment_history.py and check_brand_name.py: pass
  • Related tests (27 files: test_plugin_import*, *checkout*, *teardown*, *uninstall*; KIROCREW_PROFILE=standalone pytest -n 4): 557 passed

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.

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision c5b7c06444c9ca62415c27d555c0b1fd598940d7 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 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

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing to check: the change touches comments only and leaves no code, contract or user-visible surface different.

[DESIGN-REVIEWED] c5b7c06

Description read

[DESCRIPTION-READ] f58d65cffc5628e9a207d3e1fa2fbb864b23a63ec40bdd1b72c53a6290cb7d1a

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

First Principles Review (Opus 5.5) — ✅ PASS

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

Only comments change; every rewrite drops the review-round history and keeps the rule. Nothing ships that a user or the runtime would notice.

What this change ships

Inventory (5 items) — 5 justified

Intent: make the app platform core's comments explain the rule rather than how the fix was reached. This is a FIX (comment hygiene).

  1. The bounded-dict comment in plugin_import.py names the fields it covers instead of counting review rounds — justified
  2. The destination-lifecycle and pinned-install comments in registry_pipeline/checkout.py state the invariant instead of "earlier drafts" or "four review rounds" — justified
  3. The WARNING-level comment in registry_pipeline/install.py gives the reason without the bug's history — justified
  4. The config-lock comment in routes_uninstall.py drops "does not belong in this change" — justified
  5. The withdrawing_trust comment in teardown.py says "opposite risks" instead of "opposite review findings" — justified

[FIRST-PRINCIPLES-REVIEWED] c5b7c06

Description read

[DESCRIPTION-READ] 7f01aea4f2df8c770919a6bdd9d2053d4bf317290c38dde972797d163602e9c6

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

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] c5b7c06

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

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c5b7c06

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

@iamwhatever

iamwhatever commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor Author

Backend Tests (Windows) (6) red at a481f9b: test_slack_team_id_env.py::TestSpawnEnv fails with WinError 2 on main. That is tracked in #24612 (from #22380), with open fixes #24609 and #24613, and is not this diff (comments only). I will rebase as soon as either fix merges.

@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 27, 2026
Rewrite five comments in src/kiro_crew/apps (outside builtins) that
narrated review rounds or 'this change' so each states the rule it
guards. Comments only; the AST of every touched file is unchanged.
@iamwhatever

iamwhatever commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor Author

Rebased onto main 8a518e1 to pick up #24609 (5c11e4d), the fix for the Windows (6) red (#24612). New head c5b7c06, same patch (astcheck against the merge base: 5 files, 0 code changed; comment-history and brand gates pass).

@iamwhatever
iamwhatever force-pushed the chore/src-comments-apps-core branch from a481f9b to c5b7c06 Compare October 27, 2026 01:18
@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 27, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Backend Tests (3.12, 4) red at c5b7c06: test_remote_workspace_file_integrity.py::test_a_regex_that_overflows_is_a_tool_error_not_a_dead_server failed on an unraisable RecursionError. That is the known flake #23382, not this diff (comments only). I will rerun the shard once the run finishes.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 27, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 27, 2026 04:09

@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 (5 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 in five source files; no code line changes.

@KiroCrewCaptain
KiroCrewCaptain merged commit 84c4235 into main Oct 27, 2026
157 of 159 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the chore/src-comments-apps-core branch October 27, 2026 04:09
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 27, 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