Repository navigation
chore(dashboard): strip history narration from comments - #9333
Conversation
c98ccc6 to
ffdc5a1
Compare
First Principles Review (Fable 5) — ✅ PASSPremise-level review of The spot checks across First-Principles-Verdict: PASS Spot-check the present-tense rewrites in security-gate comments ( Not justified as shipped
What this change shipsInventory (4 items) — 3 justifiedIntent: bring dashboard comments into compliance with the documented "Comments explain the WHY" rule — a FIX (of rule violations), mandated by
Counted: 92 files in the patch (grepped [FIRST-PRINCIPLES-REVIEWED] 71abe77 |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Mechanical cleanup enforced by the existing ratchet gate; spot-checks confirm rationale is preserved and the diff is genuinely comment/docstring-only. The change services an already-established rule ( Suggestions
[DESIGN-REVIEWED] 71abe77 |
Opus 4.8 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 5.6 Review — ✅ no blocking findingsGPT 5.6 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: |
ffdc5a1 to
196a984
Compare
466a8cd to
dd5f98f
Compare
dd5f98f to
51b78f1
Compare
3de3486 to
5b99f4f
Compare
Disposition: First Principles BLOCK — not reproducible, stale baseThe finding says this patch carries the whole The rider it named is main's own commit. Rebased onto current No code changed in response to this finding, because there was nothing to change. The |
5b99f4f to
5c08f30
Compare
Comments in src/kiro_crew/dashboard/ carried a change log: PR and issue numbers, review-round and finding markers, commit SHAs, and sentences about what the code used to do. code-style.md forbids all of it, because a comment that narrates a change is stale the moment the next change lands and a reader cannot tell whether it describes the code in front of them. Every remaining comment now states current behaviour in present tense. Invariants, edge cases, units and the reason a surprising choice is correct are kept verbatim; only the reference to how the code got there is gone. Comments that carried nothing beyond the reference are deleted. Comments and docstrings only. No executable code, identifier, log string or user-facing string changes.
5c08f30 to
71abe77
Compare
) Comments in src/kiro_crew/dashboard/ carried a change log: PR and issue numbers, review-round and finding markers, commit SHAs, and sentences about what the code used to do. code-style.md forbids all of it, because a comment that narrates a change is stale the moment the next change lands and a reader cannot tell whether it describes the code in front of them. Every remaining comment now states current behaviour in present tense. Invariants, edge cases, units and the reason a surprising choice is correct are kept verbatim; only the reference to how the code got there is gone. Comments that carried nothing beyond the reference are deleted. Comments and docstrings only. No executable code, identifier, log string or user-facing string changes. Co-authored-by: zejiangg <zejiangg@amazon.com>
Problem / Motivation
Comments in
src/kiro_crew/dashboard/had turned into a change log. They carried PRand issue numbers, review-round and finding markers (
(#2696) GPT round, blocking,B2/B5,server review finding), commit SHAs, and whole sentences about what thecode used to do before some fix landed.
docs/system-specs/common/code-style.md, section "Comments explain the WHY", alreadyforbids all of that. A comment carries invariants, edge cases, units, and the reason a
surprising choice is correct. History lives in git.
Why it matters
A comment that narrates a change is stale the moment the next change lands. A reader
cannot tell whether it describes the code in front of them or the code from two fixes
ago. The reference numbers make it worse: to trust the line you have to go read a
closed PR, and the line itself stops saying what the rule is.
What changed (motivation → approach → change)
Every comment and docstring in
src/kiro_crew/dashboard/was read against thecode-style rule.
Where a comment named a PR, an issue, a review round, a finding, a SHA or a date, the
reference was deleted and the sentence around it kept.
# Strip trailing control-tag lines FIRST (#7948): this leg mirrors a ...becomes# Strip trailing control-tag lines first: this leg mirrors a ....Where a comment told a story, it now states current behaviour in present tense.
# The flag used to be per-turn, not per-action (issue #7681). That silently broke deny -> discuss -> revise -> retry.becomes# The flag is per-action, not per-turn: a per-turn flag breaks deny -> discuss -> revise -> retry.The reason stays; thehistory goes.
Where a comment had nothing left once the reference came out, the comment was deleted.
Every invariant, edge case, unit, ordering constraint and "why this surprising choice
is correct" was kept.
Directory covered:
src/kiro_crew/dashboard/, all.pyfiles recursively, includinghandlers/. 91 of 105 files needed a change. Comments and docstrings only — noexecutable code, identifier, log string, user-facing string or test changed.
# type: ignore,# noqaand pragma lines are untouched, as the rule exempts them.Violation count, measured as comment/docstring lines matching the audit patterns
(scoped to comment and docstring tokens only, so string literals and code do not
count):
previously,we now,Status: implemented)The 28 remaining strict hits and the 240 loose hits are false positives that must stay:
present-tense runtime state, not repo history.
# auto-close cards that kiro-cli no longer reports,# reject previously-unseen IPs rather than evicting a live one,a review round is exactly when a PR's lifecycle moved(the domain concept, not thisrepo's review process), the word "finding" as an ordinary noun, and hex values that are
data.
Tests
None added. This is a comment-only change, so there is no behaviour to lock in.
The diff was machine-checked to be comment-only: for each of the 91 files the token
stream at
HEAD~1and atHEADwere compared withtokenize, ignoringCOMMENTtokens and docstring
STRINGtokens. All 91 files are token-identical on every othertoken, so no executable code moved.
Manual verification
Gates, all run under the repo's 3.12 toolchain:
Dashboard tests:
pytest test -k dashboard -q— 3466 passed, 2 skipped.test/test_host_isolation_floor.pyis deselected from that run: it fails 16 tests onthis host, identically on a clean
origin/mainworktree, because the pinned-pathassertions resolve against the real
$HOME. Confirmed pre-existing and unrelated.CHANGELOG.mdis untouched: it is append-only and written by the release PR, perAGENTS.md.
Related Issues
N/A — no tracking issue.
Checklist
existing spec rather than changing it