Repository navigation
refactor: correct stale lifecycle docs in the tracing module - #35651
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks. The docstrings and spec now describe the code as it is, and the one dropped conditional behaves the same for the [DESIGN-REVIEWED] 9a05598 Description read[DESCRIPTION-READ] 9bb34a642bd3f07ba29ed8ff0d9f5aaca4d7df9021f30a0b30f2be8976db23b7 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. This is prose correction plus one dead conditional. Both Notes
What this change shipsInventory (7 items) — 6 justifiedIntent: make the tracing module's prose match what the code does about when the switch is read and which tracer is kept. FIX (documentation only).
[FIRST-PRINCIPLES-REVIEWED] 9a05598 Description read[DESCRIPTION-READ] 6df5f366e3bb7757ed1062ea2b59cd2a0413c6fa586e857799954ee488958085 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 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 6.1 Review — ✅ no blocking findingsGPT 6.1 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: |
|
|
The backend reds on 58bb158 are main's, not this diff's. Every failing shard has exactly one failure, and each is one of the two main breaks tracked in #35660; both fail the same way on a pristine
No push and no override for these reds: the branch rebases onto main once both fixes land. |
58bb158 to
b069b66
Compare
|
Rebased onto Re-gated on the new head ( |
|
b069b66 to
7d7218f
Compare
|
Rebased: main moved in docs/system-specs/modules/metrics.md since this head went green (9dc068e -> 839281e); CI re-running. The base change in |
|
Code change approver recommendation: ApproveWhy: the decider estimates a 4% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes. I'm approving this PR. Every rewritten docstring and comment matches what the code actually does. The tracing switch is resolved only through An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
7d7218f to
87764e5
Compare
|
Rebased: main moved in docs/system-specs/modules/ and src/kiro_crew/slack/gateway_runtime/service_boot.py since this head went green (839281e -> cf4578c); CI re-running. No base commit touched a file this PR changes: the overlap is same-directory spec docs plus |
|
The tracing switch is read on a thread watch_config() starts at gateway boot, and again on the worker thread that applies a telemetry.* write moving one of its inputs; the turn paths only peek(), and the process keeps the one tracer it builds. The provider.py module, peek(), resolved() and _apply_config_change() docstrings, a turns.py comment, the metrics spec and two test comments still said a turn resolves the switch itself, that a write drops or rebuilds the tracer, and that a process with no watcher keeps the value it read first. They now describe the code. turn_trace_id's docstring now names the lowercasing and the all-zero refusal the code applies, the ALLOWED_KEYS comment names the test file that actually pins it, and _origin_for drops a conditional whose two branches give the same value for every str it is called with.
87764e5 to
9a05598
Compare
|
Rebased: main moved in docs/system-specs/modules/ since this head went green (cf4578c -> ccee605); CI re-running. The previous head's one red, The base commits touching |
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Tier 1 auto-approve: refactor (7 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 and docstring corrections in the tracing module plus one equivalent expression; no behaviour change for its callers. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/system-specs/modules/metrics.md.
Problem / Motivation
Goal: Make the tracing module's docstrings, comments and spec say what its code does about when the tracing switch is read and which tracer is kept, without changing any behaviour.
The tracing switch (
telemetry.traces_enabled) is read on a worker thread:watch_config()starts that read at gateway boot, and its config applier repeats it after atelemetry.*write that moves one of the switch's inputs. Turn code only callspeek(), and a process keeps the one tracer it builds. Several docstrings, one code comment, the metrics spec and two test comments still described a different lifecycle: that a turn resolves the switch itself (peek()saidturns.tracedawaitscurrent()), that a write drops or rebuilds the tracer, and that a process with no watcher keeps the value it read first.Why it matters
Nothing is broken at runtime. A reader who trusts these lines gets the module wrong: they would look for a read in
turns.tracedthat does not exist, expect the CLI to trace with the value it read first when it never reads it, and expect a rebuild where the code keeps the same tracer. AUTOSDE'srecurring-defect-patternsrule exists because prose that contradicts the code here has shipped as bugs before.Not a goal
test_only_a_write_to_a_tracer_input_rebuilds_it. Its name says "rebuilds", but renaming a test changes its node id; that is not a docs fix.slack,dashboardanddecisions.What changed (motivation → approach → change)
Every sentence about the tracing lifecycle now matches the code. One dead branch is gone.
tracing/provider.pymodule docstringcurrent(); a write drops the tracer; no watcher keeps the first valuewatch_config()starts; a process with no watcher never reads the switch and is not tracedpeek(),resolved(),_apply_config_change()tracedawaitscurrent(); read "since the last rebuild"; "the next turn resolves again" with "the same tracer"Nonetracing/turns.pytool_startedcomment, twotest_tracing_turns.pycommentscurrent()is "what traced() awaits"current()is whatwatch_config()startsdocs/system-specs/modules/metrics.md, Traces "Switch"tracing/ids.pyturn_trace_idtracing/correlation.pyALLOWED_KEYStest_tracing_ids_attrs.py, which pins ittracing/subagents.py_origin_forconversation_key.removeprefix(...) if conversation_key else ""conversation_key.removeprefix(...): both branches give""for an empty string, and both callers always pass astrThe module detector reports 0 mechanical sites for
tracing; these are judgment-class sites (false comments, one branch that cannot differ from its sibling).Backwards compatibility
Compatible: the only code change is equivalent for every
str, and both callers of_origin_forpass astr(bind_childthroughstr(... or ""),completion_bindingby its""default).Removes nothing: no name, key, path or behaviour is removed; one conditional whose branches agree is dropped.
Tests
No test change in behaviour: the diff changes no behaviour, and two edits in
test/tracing/test_tracing_turns.pyare comments.On this head (one commit on
origin/main), on the Python 3.12 CI-parity venv:test/tracing/,test_facade_mirror_guards.py,test_host_isolation_floor.py, and the two tests that readmetrics.md(test_crew_mode_metrics.py,metrics/test_crew_log_health.py) pass, and so doestest_flake_pattern_ratchet.py(68 passed). For the touched test file,test_turning_tracing_off_during_a_slow_first_build_still_turns_it_offpassed 20 of 20 runs at-n0and 10 of 10 at-n 4 --dist loadgroupbeside two sibling files, and the whole file passed in a shuffled order (seed 27800, 46 passed). Static gates green: flake8, isort, mypy, the black baseline gate, subprocess encoding, comment history, brand name, harness parity, file line cap,docs_lint.py --test,docs-lint.sh,check_per_file_coverage.py --test(the checker's self-test), vendor manifest, and the repository's semgrep rules diff-scoped. Backend-only: nothing underwebsite/,.github/orscripts/changes.Pre-push review fleet of seven: the two CI-contract reviewers (GPT and Opus contracts; the GPT one ran on Opus, at reduced fidelity) and five lenses (AUTOSDE blocking rules, behaviour preservation, import semantics and text pins, security keystone and boot path, comment accuracy). Behaviour: every changed file other than
subagents.pyis AST-identical to its base once docstrings are set aside, and a 1,920-case differential harness over_origin_forfound no divergence. No lens found a code defect; no import changed; no keystone file is touched; nothing reads the changed text as a pin. The comment lens found two missed sites of the same false claim (turns.py'stool_startedcomment,resolved()), the AUTOSDE lens found that the rewritten_apply_config_changeline still said "the same tracer" where the first switch-on builds one, and the import lens found a fourth (atest_tracing_turns.pycomment). An independent adjudicator upheld all four, with corrected wording; all are fixed in this head, and a verifier confirmed the fixes. Dropped: the Opus-contract reviewer's two discovery candidates, which it refuted itself (no caller passes a non-strto_origin_for; a write that lands before the boot read finishes still ends with the right switch).Manual verification
N/A — unit coverage sufficient: the change is prose plus one conditional proven equivalent for every value its callers pass.
Screenshots / video
Why no screenshot: backend-only docstring, comment and spec edits under
src/kiro_crew/tracing/, plus one equivalent conditional; nothing renders differently.Related Issues
Part of #16523
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)