Skip to content

refactor: correct stale lifecycle docs in the tracing module - #35651

Merged
bolichen97 merged 1 commit into
mainfrom
refactor/simplify-tracing
Nov 12, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
refactor/simplify-tracing

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

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 a telemetry.* write that moves one of the switch's inputs. Turn code only calls peek(), 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() said turns.traced awaits current()), 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.traced that 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's recurring-defect-patterns rule exists because prose that contradicts the code here has shipped as bugs before.

Not a goal

  • Changing when the switch is read, which tracer is served, or what any span carries.
  • Renaming 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.
  • The other modules' sweeps and the detector's known leftovers in slack, dashboard and decisions.

What changed (motivation → approach → change)

Every sentence about the tracing lifecycle now matches the code. One dead branch is gone.

Where Old claim Now says
tracing/provider.py module docstring built on first use, rebuilt on a config change; read the first time a turn asks current(); a write drops the tracer; no watcher keeps the first value built once the switch reads on and kept across config changes; read on the thread watch_config() starts; a process with no watcher never reads the switch and is not traced
peek(), resolved(), _apply_config_change() traced awaits current(); read "since the last rebuild"; "the next turn resolves again" with "the same tracer" resolution happens off the loop on those two threads; resolved since start or since a clear; the applier resolves at once and serves the kept tracer, or a first one, or None
tracing/turns.py tool_started comment, two test_tracing_turns.py comments a write makes the next turn (or new turns) re-read the switch; current() is "what traced() awaits" a write re-reads the switch; current() is what watch_config() starts
docs/system-specs/modules/metrics.md, Traces "Switch" a moving write "makes the next turn re-read the switch" the worker thread applying that write re-reads it at once
tracing/ids.py turn_trace_id the id itself "when it is 32 lowercase hex" lowercased, 32 hex digits and not all zero, as the code checks
tracing/correlation.py ALLOWED_KEYS "Pinned by test_tracing_attrs.py" (no such file) names test_tracing_ids_attrs.py, which pins it
tracing/subagents.py _origin_for conversation_key.removeprefix(...) if conversation_key else "" conversation_key.removeprefix(...): both branches give "" for an empty string, and both callers always pass a str

The 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_for pass a str (bind_child through str(... or ""), completion_binding by 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.py are 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 read metrics.md (test_crew_mode_metrics.py, metrics/test_crew_log_health.py) pass, and so does test_flake_pattern_ratchet.py (68 passed). For the touched test file, test_turning_tracing_off_during_a_slow_first_build_still_turns_it_off passed 20 of 20 runs at -n0 and 10 of 10 at -n 4 --dist loadgroup beside 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 under website/, .github/ or scripts/ 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.py is AST-identical to its base once docstrings are set aside, and a 1,920-case differential harness over _origin_for found 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's tool_started comment, resolved()), the AUTOSDE lens found that the rewritten _apply_config_change line still said "the same tracer" where the first switch-on builds one, and the import lens found a fourth (a test_tracing_turns.py comment). 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-str to _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

  • 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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 11, 2026 23:18
@bolichen97
bolichen97 requested a review from CrysisDeu November 11, 2026 23:19
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 11, 2026
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 9a055983d4ff269823ec76bed6514be991762483 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 Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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 str values both callers pass.

[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 .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 Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 9a055983d4ff269823ec76bed6514be991762483 — 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 blocks. This is prose correction plus one dead conditional. Both _origin_for callers pass a str, so the dropped branch could never differ from the kept one.

Notes

  • Item 7 — rides along: if conversation_key else "" is dropped from a change whose Goal is "docstrings, comments and spec". It is equivalent for every str: 2 callers at subagents.py:138 and subagents.py:238, both passing a str, and the description declares it. No action needed.

What this change ships

Inventory (7 items) — 6 justified

Intent: 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).

  1. The provider.py module docstring now says the switch is read on the watch_config() thread and the tracer is kept — justified
  2. The peek(), resolved() and _apply_config_change() docstrings now describe where resolution really happens — justified
  3. The metrics.md "Switch" paragraph now says the applier re-reads the switch at once — justified
  4. The turns.py comment and two test comments drop the "next turn re-reads" claim — justified
  5. The turn_trace_id docstring now states the lowercase and not-all-zero checks — justified
  6. The ALLOWED_KEYS comment now names the pin file that exists — justified
  7. A redundant empty-string branch is removed from _origin_for — rides along, equivalent for every str

[FIRST-PRINCIPLES-REVIEWED] 9a05598

Description read

[DESCRIPTION-READ] 6df5f366e3bb7757ed1062ea2b59cd2a0413c6fa586e857799954ee488958085

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 Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 9a05598

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

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

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 9a055983d4ff269823ec76bed6514be991762483 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9a05598

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

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 7 — rides along (Note on a PASS)

Accepted as described, no change: the _origin_for edit is the sweep's dead-branch class, and the Goal's "without changing any behaviour" holds for it.
"".removeprefix("subagent:") is "", so both branches of the dropped conditional give the same value for every str; both callers pass a str (bind_child via str(... or ""), completion_binding via the "" default).
Pre-push behaviour lens: 1,920-case differential harness, old vs new, no divergence in value or type; the line stays inside with _lock:.

@bolichen97
bolichen97 enabled auto-merge (squash) November 11, 2026 23:48
@bolichen97

bolichen97 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor Author

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 origin/main worktree. This PR touches only src/kiro_crew/tracing/, one test/tracing/ file and the metrics spec.

Check Its one failure Fix
Backend Tests (3.12, 6), Backend Tests (Windows) (4) test/test_updates_handlers_facade.py::test_every_name_served_from_outside_the_family_is_visible_to_type_checkers (manifest misses _running_version); reproduced red on origin/main 26e8e9e, 1 failed, 8 passed #35614
Backend Tests (3.12, 5), Backend Tests (Windows) (2) test/test_wait_discipline_ratchet.py::test_the_scan_matches_known_sites (test/test_update_boot_apply.py:335 wait_for(10s) has no baseline line) #35625
Coverage Gate fails closed on the shard reds above; nothing measured against this diff follows the two

No push and no override for these reds: the branch rebases onto main once both fixes land.

@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 Nov 12, 2026
@bolichen97
bolichen97 force-pushed the refactor/simplify-tracing branch from 58bb158 to b069b66 Compare November 12, 2026 07:38
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased onto origin/main 9dc068e8d4 so this head carries #35625, the fix for the two main breaks (#35660, now closed) that redded the previous head 58bb1581cf. The diff is byte-identical to the one the lanes judged; main changed none of this PR's files in between.

Re-gated on the new head (b069b66d8f): 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, vendor manifest all exit 0; test/tracing/ (121 passed) and test/metrics/ + test_crew_mode_metrics.py (1805 passed) green. CI re-running.

@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 Nov 12, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 6 — rides along (Note on a PASS)

Accepted as described, no change: the _origin_for edit is the sweep's dead-branch class, and the Goal's "without changing any behaviour" holds for it.
"".removeprefix("subagent:") is "", so both branches of the dropped conditional give the same value for every str; both callers pass a str (subagents.py:138 via str(... or ""), subagents.py:238 via the "" default).
Same edit and same answer as on the prior head; the rebase changed no line of this diff.

@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 Nov 12, 2026
@bolichen97
bolichen97 force-pushed the refactor/simplify-tracing branch from b069b66 to 7d7218f Compare November 12, 2026 08:44
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/metrics.md since this head went green (9dc068e -> 839281e); CI re-running.

The base change in metrics.md (#35461) is in the injection-receipt section, not the Traces "Switch" paragraph this PR edits; the changed lines are identical. On 7d7218f5b7: the full static gate set exits 0, and test/tracing/ + test/metrics/ + test_crew_mode_metrics.py pass (1926 passed).

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 12, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 7 — rides along (Note on a PASS)

Accepted as described, no change: the _origin_for edit is the sweep's dead-branch class, and the Goal's "without changing any behaviour" holds for it.
"".removeprefix("subagent:") is "", so both branches of the dropped conditional give the same value for every str; both callers pass a str (subagents.py:138 via str(... or ""), subagents.py:238 via the "" default).
Same edit and same answer as on the prior head; the rebase changed no line of this diff.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: 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 current(), which runs on the thread watch_config() starts (service_boot.py) and on the worker thread _apply_config_change uses. All turn and dashboard hook points only call peek(), so a process that never registers the watcher (the CLI) never reads the switch. _build keeps the single _built tracer and reuses it when the switch turns back on. The ids.py docstring now matches the hex32 / not-all-zero / lowercase check, and test_tracing_ids_attrs.py exists and is the file that pins ALLOWED_KEYS. The one code change, in _origin_for, behaves the same for every str, and both callers pass a str. No test or other code relies on the old wording. Nothing changes in behaviour, so no new test is needed.

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 7d7218f5b7 · 54 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@bolichen97
bolichen97 force-pushed the refactor/simplify-tracing branch from 7d7218f to 87764e5 Compare November 12, 2026 09:44
@bolichen97

Copy link
Copy Markdown
Contributor Author

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 service_boot.py, which imports tracing.provider.watch_config (#35735 left that call alone). Full static gate set and related tests (test/tracing/, test/metrics/, test_crew_mode_metrics.py, test_services_config_hot_reload.py: 2020 passed) green on 962da060c9; one later base commit touching none of these files was absorbed with the diff-scoped gates re-run (flake8, isort, black baseline, brand, harness parity, comment history) on 87764e5da1.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 7 — rides along (Note on a PASS)

Accepted as described, no change: the _origin_for edit is the sweep's dead-branch class, and the Goal's "without changing any behaviour" holds for it.
"".removeprefix("subagent:") is "", so both branches of the dropped conditional give the same value for every str; both callers pass a str (subagents.py:138 via str(... or ""), subagents.py:238 via the "" default).
Same edit and same answer as on the prior head; the rebase changed no line of this diff.

@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 Nov 12, 2026
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.
@bolichen97
bolichen97 force-pushed the refactor/simplify-tracing branch from 87764e5 to 9a05598 Compare November 12, 2026 12:37
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/ since this head went green (cf4578c -> ccee605); CI re-running.

The previous head's one red, Backend Tests (Windows) (7) on test_mcp_policy_instance_binding.py::TestAcquisitionBeforeTheAnnounce::test_past_the_budget_a_stub_is_refused_capacity_with_no_fallback (an extra queued frame inside a 0.2 s wait budget), is the Windows flake #35733, fixed on main by #35778; that head's base predated the fix, and this one carries it. This diff touches nothing under mcp_gateway/.

The base commits touching metrics.md (#34763, #35345, #35460) edit the watchdog, delivered and stage-record rows, not the Traces "Switch" paragraph this PR corrects; no base commit touched src/kiro_crew/tracing/. The rebased patch is byte-identical (same git patch-id). On 9a055983d4, on the Python 3.12 CI-parity venv: flake8, isort, mypy, the black baseline gate (pinned black 26.10.1), subprocess encoding, comment history, brand name, harness parity, docs_lint.py --test, docs-lint.sh, check_per_file_coverage.py --test, file line cap, vendor manifest and semgrep 1.78.0 diff-scoped all exit 0; test/tracing/, test/metrics/, test_crew_mode_metrics.py and test_services_config_hot_reload.py (2020 passed), plus test_facade_mirror_guards.py, test_host_isolation_floor.py and the flake-pattern ratchet, pass.

@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 Nov 12, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 7 — rides along (Note on a PASS)

Accepted as described, no change: the _origin_for edit is the sweep's dead-branch class, and the Goal's "without changing any behaviour" holds for it.
"".removeprefix("subagent:") is "", so both branches of the dropped conditional give the same value for every str; both callers pass a str (subagents.py:138 via str(... or ""), subagents.py:238 via the "" default).
Same edit and same answer as on the prior head; the rebase changed no line of this diff.

@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 Nov 12, 2026

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

@bolichen97
bolichen97 merged commit 23af1eb into main Nov 12, 2026
99 checks passed
@bolichen97
bolichen97 deleted the refactor/simplify-tracing branch November 12, 2026 14:33
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 12, 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