Tag one use_case test per os-backlog command for journeys

jared commented

2026-11-02 22:35:20 +00:00

Owner

Problem

Journey coverage on os-backlog is 23 of 99 classes.
Journeys come only from tests that call use_case.
os-backlog has one such test, so the model has one journey.
The other 76 classes get no journey, and the pattern and shape detectors report them as untraced.

Ruling 2026-11-02 (session c39c41b9): every entry point gets a journey. Entry points are each bin/os-backlog command, bin/decision-sweep, bin/wakeup-poll, and each hook. Hooks are "just as important as the executables". When every entry point is traced, code that no journey touches is a signal on its own: no use case reaches it. Untouched does not mean bad. It is never grounds for deletion by itself.

Observed

$ plugins/os-sdlc/bin/system-model coverage /home/jared/dev/cc-os/plugins/os-backlog
coverage: 23/99
Backlog::CLI::Commands
...

Tracer#tagged_tests (plugins/os-sdlc/lib/os_sdlc/system_model/tracer.rb:48) keeps only test files in which a call node named use_case exists. It runs those tests in process against fixtures. It never runs bin/ directly.
In plugins/os-backlog/tests that matches one file: tests/comment_cli_test.rb:23, in test_comment_with_body_posts_and_confirms, tag os-backlog comment. tests/test_helper.rb:16 defines the no-op use_case helper.
The other 65 test files have no use_case call. 12 of them drive the CLI in process with run_cli. tests/decision_sweep_test.rb covers bin/decision-sweep. No test covers bin/wakeup-poll.
The only hook is hooks/session_start.rb (Ruby since #1522, entry object Backlog::SessionStart, registered in hooks/hooks.json). tests/session_start_test.rb covers it.
Journey views are already committed: plugins/os-backlog/design/generated/journeys/os_backlog_comment.c4 is tracked. The Writer regenerates them on system-model build.
Cause 2 (checked, not a cause of the 76): lazy loads. The close note of #1505 says the first traced journey absorbs the Boot::Commands lazy-load calls (39 messages), kept on purpose; Tracer::SEED = 0 keeps it stable.

Reproduce

plugins/os-sdlc/bin/system-model coverage /home/jared/dev/cc-os/plugins/os-backlog | head -1

Approach

Tag one existing in-process test per Ruby entry point with use_case, as tests/comment_cli_test.rb:23 does. Wrap the body of one existing test method. Change no assertion. Do not change the Tracer.

Each command passed to run_cli in plugins/os-backlog/tests: tag os-backlog <command>.
bin/decision-sweep: tag one test in tests/decision_sweep_test.rb as decision-sweep.
hooks/session_start.rb: tag one test in tests/session_start_test.rb as session-start.
bin/wakeup-poll: it has no test. Add one in-process test that runs it against a fixture and tag it wakeup-poll. This is the only new test.
A guard test enforces the rule by scanning: every run_cli command, every Ruby file in bin/, and every Ruby file in hooks/ has a matching use_case tag. A new command, executable, or hook without a tag fails the guard.
Then run system-model build for os-backlog and commit the regenerated design/generated/ files, including the new journeys/*.c4. The committed journeys are the recorded traces; review changes to them as git diffs.

Required work:

Tag one in-process test per run_cli command — check: present use_case("os-backlog in plugins/os-backlog/tests/*_test.rb
Tag decision-sweep and session-start, and add plus tag a wakeup-poll test — check: present use_case("wakeup-poll") in plugins/os-backlog/tests/*_test.rb
Add the guard test — check: present use_case in plugins/os-backlog/tests/use_case_tag_coverage_test.rb
Commit regenerated journeys — check: present wakeup-poll in plugins/os-backlog/design/generated/journeys/*.c4

Acceptance criteria

Given each distinct command word passed to run_cli in plugins/os-backlog/tests/*_test.rb each Ruby file in plugins/os-backlog/bin/, and each Ruby file in plugins/os-backlog/hooks/, when the guard test runs, then a matching use_case tag exists for each one.
Given the tagged tests, when system-model coverage plugins/os-backlog runs, then the touched count is higher than 23.
Given the Tracer, when it runs twice on os-backlog, then both runs print the same coverage line.
Given the tagged tests run without the recorder, when bundle exec ruby plugins/os-backlog/tests/all.rb runs, then the suite passes with no existing assertion changed.
Given system-model build on os-backlog, then design/generated/journeys/ holds one .c4 file per tag, and the files are committed.

Owner sketch

class UseCaseTagCoverageTest < Minitest::Test
  def test_every_run_cli_command_has_a_use_case_tag
  def test_every_bin_executable_has_a_use_case_tag
  def test_every_hook_has_a_use_case_tag
end

Non-goals

Tracer changes. Excluding boot messages from the touched count. Counting journeys per class. Method-level tracing. Cause labels for untouched classes. The residue ruling on classes that stay untouched.

Origin

Trigger: plugins/os-sdlc/bin/system-model coverage plugins/os-backlog prints coverage: 23/99.
Widened 2026-11-02 after a round-table (devils-advocate, measurement, premortem, simplifier) and Jared's rulings in session c39c41b9: entry points include all bin/ executables and hooks; option A, commit generated journeys.
Chain: 76 classes untraced ← only one test file calls use_case ← DESIGN (plugins/os-sdlc/lib/os_sdlc/system_model/tracer.rb:48 traces tagged tests only; plugins/os-backlog/tests/comment_cli_test.rb:23)
VERDICT: CREATE
Where: plugins/os-backlog/tests/comment_cli_test.rb:23
Session: d077e084-9195-4803-b761-6ce01eca0249; widened in c39c41b9-9d91-42f2-8487-5c11d60c40b4

## Problem Journey coverage on os-backlog is 23 of 99 classes. Journeys come only from tests that call `use_case`. os-backlog has one such test, so the model has one journey. The other 76 classes get no journey, and the pattern and shape detectors report them as untraced. Ruling 2026-11-02 (session c39c41b9): every entry point gets a journey. Entry points are each `bin/os-backlog` command, `bin/decision-sweep`, `bin/wakeup-poll`, and each hook. Hooks are "just as important as the executables". When every entry point is traced, code that no journey touches is a signal on its own: no use case reaches it. Untouched does not mean bad. It is never grounds for deletion by itself. ## Observed ``` $ plugins/os-sdlc/bin/system-model coverage /home/jared/dev/cc-os/plugins/os-backlog coverage: 23/99 Backlog::CLI::Commands ... ``` `Tracer#tagged_tests` (`plugins/os-sdlc/lib/os_sdlc/system_model/tracer.rb:48`) keeps only test files in which a call node named `use_case` exists. It runs those tests in process against fixtures. It never runs `bin/` directly. In `plugins/os-backlog/tests` that matches one file: `tests/comment_cli_test.rb:23`, in `test_comment_with_body_posts_and_confirms`, tag `os-backlog comment`. `tests/test_helper.rb:16` defines the no-op `use_case` helper. The other 65 test files have no `use_case` call. 12 of them drive the CLI in process with `run_cli`. `tests/decision_sweep_test.rb` covers `bin/decision-sweep`. No test covers `bin/wakeup-poll`. The only hook is `hooks/session_start.rb` (Ruby since #1522, entry object `Backlog::SessionStart`, registered in `hooks/hooks.json`). `tests/session_start_test.rb` covers it. Journey views are already committed: `plugins/os-backlog/design/generated/journeys/os_backlog_comment.c4` is tracked. The Writer regenerates them on `system-model build`. Cause 2 (checked, not a cause of the 76): lazy loads. The close note of #1505 says the first traced journey absorbs the `Boot::Commands` lazy-load calls (39 messages), kept on purpose; `Tracer::SEED = 0` keeps it stable. ## Reproduce ``` plugins/os-sdlc/bin/system-model coverage /home/jared/dev/cc-os/plugins/os-backlog | head -1 ``` ## Approach Tag one existing in-process test per Ruby entry point with `use_case`, as `tests/comment_cli_test.rb:23` does. Wrap the body of one existing test method. Change no assertion. Do not change the Tracer. - Each command passed to `run_cli` in `plugins/os-backlog/tests`: tag `os-backlog <command>`. - `bin/decision-sweep`: tag one test in `tests/decision_sweep_test.rb` as `decision-sweep`. - `hooks/session_start.rb`: tag one test in `tests/session_start_test.rb` as `session-start`. - `bin/wakeup-poll`: it has no test. Add one in-process test that runs it against a fixture and tag it `wakeup-poll`. This is the only new test. A guard test enforces the rule by scanning: every `run_cli` command, every Ruby file in `bin/`, and every Ruby file in `hooks/` has a matching `use_case` tag. A new command, executable, or hook without a tag fails the guard. Then run `system-model build` for os-backlog and commit the regenerated `design/generated/` files, including the new `journeys/*.c4`. The committed journeys are the recorded traces; review changes to them as git diffs. Required work: 1. Tag one in-process test per `run_cli` command — check: present `use_case("os-backlog ` in `plugins/os-backlog/tests/*_test.rb` 2. Tag `decision-sweep` and `session-start`, and add plus tag a `wakeup-poll` test — check: present `use_case("wakeup-poll")` in `plugins/os-backlog/tests/*_test.rb` 3. Add the guard test — check: present `use_case` in `plugins/os-backlog/tests/use_case_tag_coverage_test.rb` 4. Commit regenerated journeys — check: present `wakeup-poll` in `plugins/os-backlog/design/generated/journeys/*.c4` ## Acceptance criteria 1. Given each distinct command word passed to `run_cli` in `plugins/os-backlog/tests/*_test.rb` each Ruby file in `plugins/os-backlog/bin/`, and each Ruby file in `plugins/os-backlog/hooks/`, when the guard test runs, then a matching `use_case` tag exists for each one. 2. Given the tagged tests, when `system-model coverage plugins/os-backlog` runs, then the touched count is higher than 23. 3. Given the Tracer, when it runs twice on os-backlog, then both runs print the same coverage line. 4. Given the tagged tests run without the recorder, when `bundle exec ruby plugins/os-backlog/tests/all.rb` runs, then the suite passes with no existing assertion changed. 5. Given `system-model build` on os-backlog, then `design/generated/journeys/` holds one `.c4` file per tag, and the files are committed. ## Owner sketch ```ruby class UseCaseTagCoverageTest < Minitest::Test def test_every_run_cli_command_has_a_use_case_tag def test_every_bin_executable_has_a_use_case_tag def test_every_hook_has_a_use_case_tag end ``` ## Non-goals Tracer changes. Excluding boot messages from the touched count. Counting journeys per class. Method-level tracing. Cause labels for untouched classes. The residue ruling on classes that stay untouched. ## Origin - Trigger: `plugins/os-sdlc/bin/system-model coverage plugins/os-backlog` prints `coverage: 23/99`. - Widened 2026-11-02 after a round-table (devils-advocate, measurement, premortem, simplifier) and Jared's rulings in session c39c41b9: entry points include all bin/ executables and hooks; option A, commit generated journeys. - Chain: 76 classes untraced ← only one test file calls `use_case` ← DESIGN (`plugins/os-sdlc/lib/os_sdlc/system_model/tracer.rb:48` traces tagged tests only; `plugins/os-backlog/tests/comment_cli_test.rb:23`) VERDICT: CREATE - Where: plugins/os-backlog/tests/comment_cli_test.rb:23 - Session: d077e084-9195-4803-b761-6ce01eca0249; widened in c39c41b9-9d91-42f2-8487-5c11d60c40b4

jared added the

labels

2026-11-02 22:35:20 +00:00

jared commented

2026-11-03 00:00:21 +00:00

Author

Owner

Widened 2026-11-02 (session c39c41b9). Scope now covers every Ruby entry point: each run_cli command, bin/decision-sweep, and bin/wakeup-poll (wakeup-poll gets its first test). The guard checks both. Regenerated design/generated/journeys/*.c4 get committed (Jared ruled option A). Python hook tracing and the measurement follow-ups are non-goals; see the 2026-11-02 handoff.

jared referenced this issue

2026-11-03 13:50:42 +00:00

Port os-backlog hooks/session_start.py to Ruby so the journey tracer records it #1522

jared commented

2026-11-03 13:50:47 +00:00

Author

Owner

Follow-up filed: #1522 ports hooks/session_start.py to Ruby (the hook listed as a non-goal here). Ruled by Jared 2026-11-03. Items 2 to 6 of the round-table are not tickets: they are questions to ask of the map once this ticket produces it.

jared referenced this issue

2026-11-03 14:06:22 +00:00

Port os-backlog hooks/session_start.py to Ruby so the journey tracer records it #1522

jared commented

2026-11-04 17:54:57 +00:00

Author

Owner

Work started on branch ticket-1514. Body corrected before the run: the hook is Ruby since #1522, so hooks/session_start.rb is now an in-scope entry point with tag session-start. The handoff 2026-11-03-1442 records this.

jared commented

2026-11-04 18:38:59 +00:00

Author

Owner

Resolution

Done: Tagged every run_cli command word, bin/ executable, and hook with use_case; added the guard test and a wakeup-poll skip-path test; committed 13 journey files.

Evidence: Branch ticket-1514, implementation 230. Coverage 23/99 to 52/107, same on two runs. Suite: 354 runs, 0 failures. Assertion lines on main: 579, all still present. system-model build gives no diff.

Follow-ups: none filed: handoff 2026-11-03-1442 holds follow-ups until Jared rules after seeing the map. Gaps reported to Jared: 10 CLI commands outside the run_cli scope have no tag; the wakeup-poll tag traces only the skip path; the session-start wrapper journey is empty.

## Resolution **Done:** Tagged every run_cli command word, bin/ executable, and hook with use_case; added the guard test and a wakeup-poll skip-path test; committed 13 journey files. **Evidence:** Branch ticket-1514, implementation 230. Coverage 23/99 to 52/107, same on two runs. Suite: 354 runs, 0 failures. Assertion lines on main: 579, all still present. system-model build gives no diff. **Follow-ups:** none filed: handoff 2026-11-03-1442 holds follow-ups until Jared rules after seeing the map. Gaps reported to Jared: 10 CLI commands outside the run_cli scope have no tag; the wakeup-poll tag traces only the skip path; the session-start wrapper journey is empty.

jared closed this issue

2026-11-04 18:38:59 +00:00

jared referenced this issue from a commit

2026-11-04 18:40:05 +00:00

feat(os-backlog): Audited the os-backlog use_case tag change: test-only diff, contracts protected, no production correction, all WORK items present. (#1514)

jared referenced this issue from a commit

2026-11-04 18:40:05 +00:00

chore(os-backlog): commit regenerated system model and journeys (#1514)

jared referenced this issue from a commit

2026-11-04 18:40:05 +00:00

docs(os-backlog): record the journey tags in the status leaf (#1514)

jared referenced this issue from a commit