feat(telemetry): opt-in local telemetry + fix swarm fork description scope#15
Merged
Merged
Conversation
…scope
Two changes bundled — both stem from making spec/swarm flow execution
observable without misleading the observer:
1. Local telemetry (opt-in, no remote upload)
- scripts/spec_telemetry.py: emit(event, **fields) gated by
SPECODE_TELEMETRY=on. Single ~/.specode/telemetry.jsonl,
append-only, grep/jq-friendly. Rotates to .0 past
SPECODE_TELEMETRY_MAX_BYTES (default 50 MB). All IO errors
swallowed so telemetry never breaks a hook.
- Instrumented: spec.init / spec.phase_transition / spec.end /
inv.violation (INV-1..9 with spec_slug + phase) /
swarm.run_start / swarm.stage_round / swarm.stage_done /
swarm.writeback / swarm.run_end.
- spec_state.py telemetry-summary aggregates the file locally
(event counts, INV top-list, per-spec phase/violation totals,
swarm avg rounds per converged/failed stage).
2. task-swarm fork description now carries scope
- Previously a checkpoint stage's r2 coder shipped as
"阶段 N coder-r2: <title>" with no scope, and the orchestrator
commonly improvised "修复 N 个 P0" off the validator outbox,
reading as if reviewer triggered a fix loop (reviewer is
advisory and never does).
- task_swarm.py: _fork_description now adds [scope] (e.g.
[validator-fail-fix] / [advisory] / [re-run]).
- commands/task-swarm.md: tells the orchestrator to copy
<json.description> verbatim.
- agents/task-swarm-validator.md: forbids P0/P1/P2 severity
labels in fix guidance (reviewer terminology; validator fail
is itself blocking).
Tests: +16 cases (13 telemetry, 3 _fork_description). Full suite
154 passed.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
~/.specode/telemetry.jsonl) for spec/swarm flow analysis. Enabled bySPECODE_TELEMETRY=on; absolutely no remote upload. Records spec lifecycle, INV violations (withspec_slug/phase), and task-swarm run/stage/round events. Addspec_state.py telemetry-summaryfor local aggregation.validator-fail-fixwas rendering as "修复 N 个 P0" in the UI, misleading observers into thinking reviewer triggered a fix loop (reviewer is advisory and never does). Description now carries[scope]andcommands/task-swarm.mdtells the orchestrator to copy<json.description>verbatim.agents/task-swarm-validator.mdalso forbids P0/P1/P2 severity labels in fix guidance — those tags are reviewer terminology.Why bundled
Both stem from the same problem domain — making flow execution observable without misleading the observer. The description-scope fix surfaced while writing telemetry instrumentation, when state.json inspection of a real run (
design-login-page, stage 5 checkpoint) confirmed the state machine was healthy but the human-facing description was lying.Telemetry details
spec.initspec_init.pyafter spec dir createdspec.phase_transition/spec.endspec_session.update_config_sessioninv.violationspec_guard.pyon each INV-1..9 deny branchswarm.run_start/swarm.stage_round/swarm.stage_done/swarm.writeback/swarm.run_endtask_swarm.py.jsonl.0once it passesSPECODE_TELEMETRY_MAX_BYTES(default 50 MB).audit/<date>.log(always-on hook-decision audit) untouched and complementary.Test plan
python3 -m pytest plugins/specode/tests/ -q→ 154 passed (138 prior + 13 telemetry + 3_fork_description).SPECODE_TELEMETRY=on python3 scripts/spec_state.py telemetry-summaryshows by-event counts, INV top-list, per-spec aggregates, swarm avg rounds per stage.SPECODE_TELEMETRYunset does not create the file._fork_description(5, "coder", 2, "validator-fail-fix", "...")→阶段 5 coder-r2 [validator-fail-fix]: .... No "P0" in output.🤖 Generated with Claude Code