lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(scheduler-sim-repl-verbosity): add approved spec (requirements/design/tasks)

Browse source 
Full spec scaffold (requirements/design/research/tasks all approved,
ready_for_implementation=true) plus a roadmap backlog item recorded from
the dirty-content-fingerprint spec's task 4.3 findings (Makefile/meson
fingerprint-computation duplication risk).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Rongsong Shen 2026-08-22 02:45:52 +00:00
parent 1c906e955c
commit 979cd24f6c
No known key found for this signature in database
GPG key ID: 5BCDAAE0123E9FE2
6 changed files with 519 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

69
.kiro/specs/scheduler-sim-repl-verbosity/tasks.md Normal file
View file

@ -0,0 +1,69 @@
# Implementation Plan
- [ ] 1. Foundation: job identifier range compression
- [ ] 1.1 Write failing unit tests for compressing job-array identifier listings into index ranges
- Cover a single contiguous range, non-contiguous indices within one array submission, multiple distinct array submissions in one listing, a mix of array and non-array identifiers, and an output buffer too small to hold the full listing
- Observable: the new test cases execute and fail against the current codebase, which has no compression behavior yet
- _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_
- [ ] 1.2 Implement job identifier range compression so the new tests pass
- Group identifiers by their shared array submission and render contiguous index runs as a single compressed range, comma-joining non-contiguous runs
- Never drop or fabricate an identifier, and fail safely (without truncating or crashing) when the output buffer is too small
- Observable: all tests from 1.1 pass; the helper is ready for the event-echo and round-summary work to adopt
- _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_
- [ ] 2. Core: per-round decision summary, repetitive-round collapsing, and the shared range-flush capability
- [ ] 2.1 Write failing tests for round-level decision summaries, collapsing, and the shared flush capability
- Cover: a round with at least one decision produces one summary line naming decision counts and affected job identifiers; a round with zero decisions produces no individual line; two or more consecutive idle rounds collapse into a single range notification; two or more consecutive rounds with an identical decision outcome collapse into a single range notification; a collapsed range notification states its round bounds, round count, and covered time span; a change in outcome ends an active collapsed range; a job's status change between rounds is reflected in the following round's summary even without a dedicated dispatch event to observe; the shared flush capability safely does nothing when no range is active and is safe to call more than once in a row
- Observable: the new test cases fail against today's unconditional per-decision echo, which has no summarizing, collapsing, or flush behavior
- _Requirements: 2.1, 2.2, 2.4, 3.1, 3.2, 3.3, 3.4_
- _Boundary: Round Rollup_
- _Depends: 1.2_
- [ ] 2.2 Implement the round-boundary decision summary, collapsing logic, and the shared range-flush capability
- Add the state needed to track an active collapsed range across rounds
- At each round boundary during continuous execution, determine the round's decision outcome directly from current job status (not solely from decision events) together with the existing per-round decision tally, then extend an active matching range or end it and begin reporting the new outcome
- Expose the range-ending behavior so other parts of the REPL can trigger it safely, including when nothing is active; wire it into the existing replay-completion notification so a range open at end-of-replay is closed and reported before that notification prints
- Observable: all tests from 2.1 pass; replaying the real 108-round capture that motivated this feature under continuous execution now produces the hand-validated collapsed shape (an idle range before the first job arrival, one line per job arrival, and one collapsed range per stable pending stretch, with any range still open at end-of-replay closed out before the completion notice) instead of thousands of repeated lines
- _Requirements: 2.1, 2.2, 2.4, 3.1, 3.2, 3.3, 3.4, 3.6_
- _Boundary: Round Rollup_
- [ ] 3. (P) Core: mode-aware event echo, including ending an active collapsed range on structural events or breakpoint hits — Depends: 2.2
- [ ] 3.1 (P) Write failing tests for suppressing routine event chatter and for ending an active collapsed range at the right moments
- Cover: a routine per-tick event (job progress, resource usage, or resource value update) produces no line under continuous execution; the same event still produces a line while single-stepping; a structural change (new jobs, workers, resources, or configuration arriving) still produces a line under continuous execution and ends any active collapsed range first; an event matching a breakpoint still interrupts continuous execution regardless of its classification, and ends any active collapsed range before the interruption is shown
- Observable: the new test cases fail against today's unconditional per-event echo, which has no classification or range-ending behavior
- _Requirements: 1.1, 1.2, 1.3, 1.4, 3.5, 3.6_
- _Boundary: Event Echo Gate_
- _Depends: 1.2, 2.2_
- [ ] 3.2 (P) Implement the mode-aware event echo, range compression adoption, and range-ending wiring
- Suppress routine per-event lines during continuous execution while preserving full detail while single-stepping; keep structural-change lines and breakpoint interruption behavior unaffected by the classification
- Render job-arrival listings using the compressed range format
- Before printing a structural-change line, and before a breakpoint interruption is shown, end any active collapsed range first so output never interleaves out of order
- Observable: all tests from 3.1 pass; a continuous-execution run over a replay with only routine activity produces no per-event lines, a job arrival still prints one compressed line and correctly closes out any prior collapsed range, and a breakpoint hit shows the collapsed range's final state before the interactive prompt returns
- _Requirements: 1.1, 1.2, 1.3, 1.4, 3.5, 3.6, 4.5_
- _Boundary: Event Echo Gate_
- [ ] 4. (P) Integration: retire the redundant per-decision echo during continuous execution — Depends: 2.2
- [ ] 4.1 (P) Write failing tests confirming the old per-decision echo no longer duplicates the new round summary
- Cover: during continuous execution, no bare per-decision line appears outside the round summary; while single-stepping, full per-decision detail still prints exactly as before; a non-interactive (headless) replay's decision output is unaffected
- Observable: the new test cases fail while the old unconditional per-decision print path still runs alongside the new round summary
- _Requirements: 2.3, 5.1, 5.4_
- _Boundary: sim_print_decision gate_
- _Depends: 2.2_
- [ ] 4.2 (P) Suppress the old per-decision echo during continuous execution so the round summary is the sole source of decision output
- Leave single-stepping and non-interactive output untouched
- Observable: all tests from 4.1 pass; a full continuous-execution run over a replay shows only round-summary lines, with no duplicate bare decision lines
- _Requirements: 2.3, 5.1, 5.4_
- _Boundary: sim_print_decision gate_
- [ ] 5. Validation: regression and real-data verification — Depends: 3.2, 4.2
- [ ] 5.1 Verify single-stepping and every other existing REPL command remain unchanged
- Confirm single-stepping output, and the inspection/breakpoint/parameter/snapshot commands' behavior and output, match their pre-feature baseline exactly; confirm no new command was introduced
- Observable: the existing REPL test suite's pre-existing assertions all still pass unmodified, and a step-mode transcript comparison shows no textual difference from the pre-feature baseline
- _Requirements: 5.1, 5.2, 5.3_
- [ ] 5.2 Run the full scheduler test suite and re-verify against the real replay capture that originally motivated this feature
- Observable: the full test suite passes with no regressions, and re-running the interactive REPL's continuous execution against the real capture reproduces the collapsed output shape validated during design, cutting a several-thousand-line transcript down to a handful of lines while preserving every state change
- _Requirements: 2.1, 2.2, 3.1, 3.2, 3.3, 3.4_