Skip to content

chore(dashboard): strip history narration from comments - #9333

Merged
iamwhatever merged 1 commit into
mainfrom
chore/comment-audit-dashboard
Sep 9, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
chore/comment-audit-dashboard

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Comments in src/kiro_crew/dashboard/ had turned into a change log. They carried PR
and issue numbers, review-round and finding markers ((#2696) GPT round, blocking,
B2/B5, server review finding), commit SHAs, and whole sentences about what the
code used to do before some fix landed.

docs/system-specs/common/code-style.md, section "Comments explain the WHY", already
forbids 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 the
code-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; the
history 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 .py files recursively, including
handlers/. 91 of 105 files needed a change. Comments and docstrings only — no
executable code, identifier, log string, user-facing string or test changed. # type: ignore, # noqa and 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):

before after
unambiguous violations (PR/issue refs, round and finding markers, SHAs, previously, we now, Status: implemented) 392 28
all pattern hits, including known false positives 851 240

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 this
repo'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~1 and at HEAD were compared with tokenize, ignoring COMMENT
tokens and docstring STRING tokens. All 91 files are token-identical on every other
token, so no executable code moved.

Manual verification

Gates, all run under the repo's 3.12 toolchain:

python3 scripts/check_black_formatting.py     # passed, 91 files in scope
python3 scripts/check_subprocess_encoding.py  # passed
isort --check-only src/kiro_crew test          # clean
flake8 src/kiro_crew test                      # clean
mypy src/kiro_crew                             # Success: no issues in 1326 source files
BRAND_BASE_REF=origin/main python3 scripts/check_brand_name.py  # clean

Dashboard tests: pytest test -k dashboard -q — 3466 passed, 2 skipped.

test/test_host_isolation_floor.py is deselected from that run: it fails 16 tests on
this host, identically on a clean origin/main worktree, because the pinned-path
assertions resolve against the real $HOME. Confirmed pre-existing and unrelated.

CHANGELOG.md is untouched: it is append-only and written by the release PR, per
AGENTS.md.

Related Issues

N/A — no tracking issue.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality (N/A — comment-only)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A, this brings code into line with the
    existing spec rather than changing it
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and buluoray September 8, 2026 00:56
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 8, 2026
@iamwhatever
iamwhatever force-pushed the chore/comment-audit-dashboard branch from c98ccc6 to ffdc5a1 Compare September 8, 2026 01:01
@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 71abe774a1758310073e8d8bf88aec28cac1573e — 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/CONCERNS are advisory.

The spot checks across chat_runner.py, state.py, handlers/files.py, token_auth.py, and token_secret.py all show faithful rewrites — references stripped, invariants and present-tense reasons kept, and the one behavioral-sounding flip (_EXACT_ONLY_BASH_PREFIXES "prefix" → "EXACTLY") matches what the constant's own name says the code does. The verification is complete; the review follows.

First-Principles-Verdict: PASS

Spot-check the present-tense rewrites in security-gate comments (state.py bash allowlist, token_auth.py) — a tense flip that misstates behavior is silent and no test catches it.

Not justified as shipped

  1. comment-history-baseline.json update — undeclared: the description never mentions it, though it is the required check_comment_history.py --write-baseline bookkeeping (only lowers/prunes; _total 7584→6980).

What this change ships

Inventory (4 items) — 3 justified

Intent: bring dashboard comments into compliance with the documented "Comments explain the WHY" rule — a FIX (of rule violations), mandated by docs/system-specs/common/code-style.md.

  1. PR/issue numbers, SHAs, and review-round markers removed from dashboard comments — justified
  2. History narration ("used to", "now", "previously") recast as present-tense behavior statements — justified
  3. Comments with nothing left after the reference came out deleted outright — justified
  4. Ratchet baseline counts lowered/pruned in comment-history-baseline.json — undeclared (derived: the ratchet's own --write-baseline step, else the cleanup can regress ungated)

Counted: 92 files in the patch (grepped ^diff --git) = 91 dashboard .py + the baseline; matches the described 91. Changed lines scanned for code tokens — every hit is docstring prose or a trailing comment on an unchanged line. Remaining ~6980 non-dashboard hits are already recorded as deferred by the baseline's own design, not left silently.

[FIRST-PRINCIPLES-REVIEWED] 71abe77

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 71abe774a1758310073e8d8bf88aec28cac1573e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 (code-style.md) and its already-established enforcement (check_comment_history.py + baseline, which this PR shrinks per its own --write-baseline protocol). Spot-checks of the highest-risk files (token_auth.py, origin.py, chat_utils.py) show every threat rationale and invariant rewritten into present tense rather than deleted, and an independent scan of the full diff found no executable-code changes. Fully reversible; no contract, data, or failure-mode surface.

Suggestions

  • With ~6,980 baseline entries left, more sweeps like this are coming: add a .git-blame-ignore-revs file and list this commit, so mass comment rewrites don't bury git blame on 92 files.

[DESIGN-REVIEWED] 71abe77

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 71abe77

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 71abe774a1758310073e8d8bf88aec28cac1573e: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 71abe774a1758310073e8d8bf88aec28cac1573e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 71abe77

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 71abe774a1758310073e8d8bf88aec28cac1573e: <one-sentence reason>

@iamwhatever
iamwhatever force-pushed the chore/comment-audit-dashboard branch from ffdc5a1 to 196a984 Compare September 8, 2026 01:27
@iamwhatever
iamwhatever force-pushed the chore/comment-audit-dashboard branch 2 times, most recently from 466a8cd to dd5f98f Compare September 8, 2026 03:30
@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 Sep 8, 2026
@iamwhatever
iamwhatever force-pushed the chore/comment-audit-dashboard branch from dd5f98f to 51b78f1 Compare September 8, 2026 04: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 Sep 8, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 8, 2026
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Sep 8, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 8, 2026
@iamwhatever
iamwhatever force-pushed the chore/comment-audit-dashboard branch from 3de3486 to 5b99f4f Compare September 8, 2026 16:15
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Disposition: First Principles BLOCK — not reproducible, stale base

The finding says this patch carries the whole kirocrew-security-conductor agent
(installer, prompt, roster, three tests) and duplicates fe05b42b2 (#9273). It does not.
The diff is 92 files: 91 .py files under src/kiro_crew/dashboard/ plus
comment-history-baseline.json, and nothing else.

$ gh pr diff 9333 --name-only | wc -l
92
$ gh pr diff 9333 --name-only | grep -v '^src/kiro_crew/dashboard/'
comment-history-baseline.json

The rider it named is main's own commit. fe05b42b2 merged to main after the base this
PR was reviewed on, so the reviewer read those files as additions by this branch when
they were arriving from upstream:

$ git merge-base --is-ancestor fe05b42b2 origin/main && echo on-main
on-main
$ git merge-base --is-ancestor fe05b42b2 <reviewed base> || echo "not in that base"
not in that base

Rebased onto current origin/main (acc99f217), which already contains #9273, and
force-pushed as 5b99f4f24 — one commit, 0 behind. All review lanes re-run against a base
that carries the agent, so the duplication the finding describes cannot appear.

No code changed in response to this finding, because there was nothing to change. The
diff remains comments and docstrings only, machine-verified: for each of the 91 .py
files the token stream at the merge-base and at head are identical once COMMENT tokens
and docstring STRING tokens are ignored, so no executable code moved.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 8, 2026
@iamwhatever
iamwhatever force-pushed the chore/comment-audit-dashboard branch from 5b99f4f to 5c08f30 Compare September 8, 2026 19:52
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 8, 2026
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.
@iamwhatever
iamwhatever force-pushed the chore/comment-audit-dashboard branch from 5c08f30 to 71abe77 Compare September 8, 2026 23:16
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 8, 2026
@iamwhatever
iamwhatever merged commit 322c97e into main Sep 9, 2026
67 checks passed
@iamwhatever
iamwhatever deleted the chore/comment-audit-dashboard branch September 9, 2026 01:16
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 9, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
)

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

1 participant