jared/cc-os

Watch

Fork 0

Trace the handoff complete journey in plugins/os and build its site #1394

New issue

Closed

opened 2026-10-26 14:18:19 +00:00 by jared · 3 comments

jared commented

2026-10-26 14:18:19 +00:00

Owner

Problem

The system-model tracer (#1327, ADR-0300) has no journey view on a site yet.
Jared wants to see a first journey from an entry point he uses often, with few objects, so the view is easy to read.
The first journey also proves that the tracer works outside os-me.
The tracer on main is project-agnostic.
A dry run on plugins/os passed with no tracer change.

Observed

A dry run used a 3-line use_case shim in plugins/os/tests/test_helper.rb.
It wrapped the first scenario.run('complete', path) in plugins/os/tests/handoff/complete_test.rb with use_case('handoff complete') { ... }.
The suite passed: 4 runs, 0 failures.
bin/system-model build plugins/os exited 0 with 25 elements and 34 relations.
It wrote design/generated/journeys/handoff_complete.c4 with three messages:

Handoff__CLI -> Handoff__Document 'initialize'
Handoff__CLI -> Handoff__Document 'complete'
Handoff__Document -> Handoff__Stamp 'format'

Open risk: in the generated lib_handoff.c4, relation sources are bare (Handoff__CLI -> lib_handoff.Handoff__Document) outside the module block.
build exited 0, but likec4 validate was not run separately.
Calls into core Ruby (File.binwrite) are not traced.
This is known and documented.

Reproduce

n/a: this is a feature ticket. The dry run above is the evidence.

Approach

The shim, from the ADR-0300 owner sketch:

module UseCase
  def use_case(_name) = yield
end
Minitest::Test.include(UseCase)

Required work:

Add the UseCase shim — check: present def use_case(_name) = yield in plugins/os/tests/test_helper.rb
Wrap the handoff complete path — check: present use_case('handoff complete') in plugins/os/tests/handoff/complete_test.rb
Commit the generated journey view — check: present dynamic view handoff_complete in plugins/os/design/generated/journeys/handoff_complete.c4

Orchestrator work: run plugins/os-sdlc/bin/system-model build plugins/os, then likec4 validate. Show Jared the view with system-model serve plugins/os.

Acceptance criteria

Given the plugins/os suite, when it runs without the tracer, then it passes.
Given plugins/os-sdlc/bin/system-model build plugins/os, when it finishes, then plugins/os/design/generated/journeys/handoff_complete.c4 holds the three messages above and likec4 validate accepts the model.
Given system-model serve plugins/os, when Jared opens the handoff_complete view, then he sees the three numbered messages.

Owner sketch

module UseCase
  def use_case(_name) = yield
end

Non-goals

os-me journeys stay in #1392.
Tracing calls into core Ruby is out of scope.

Origin

Trigger: dry run of the #1327 tracer on plugins/os in this session.
Improvised this session: none. The dry run edits were not kept.
Chain: feature ← #1327 (tracer), ADR-0300; os-me journeys stay in #1392
Root candidate: none found; searched journey, trace, use_case, system-model, handoff complete, dynamic view, plugins/os
Where: plugins/os/tests/test_helper.rb, plugins/os/tests/handoff/complete_test.rb
Session: 0bd25a72-f8ca-4331-a047-9cefdb9b0e3b
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os--claude-worktrees-fast-batch-15/0bd25a72-f8ca-4331-a047-9cefdb9b0e3b.jsonl

## Problem The system-model tracer (#1327, ADR-0300) has no journey view on a site yet. Jared wants to see a first journey from an entry point he uses often, with few objects, so the view is easy to read. The first journey also proves that the tracer works outside os-me. The tracer on main is project-agnostic. A dry run on `plugins/os` passed with no tracer change. ## Observed A dry run used a 3-line `use_case` shim in `plugins/os/tests/test_helper.rb`. It wrapped the first `scenario.run('complete', path)` in `plugins/os/tests/handoff/complete_test.rb` with `use_case('handoff complete') { ... }`. The suite passed: 4 runs, 0 failures. `bin/system-model build plugins/os` exited 0 with 25 elements and 34 relations. It wrote `design/generated/journeys/handoff_complete.c4` with three messages: ``` Handoff__CLI -> Handoff__Document 'initialize' Handoff__CLI -> Handoff__Document 'complete' Handoff__Document -> Handoff__Stamp 'format' ``` Open risk: in the generated `lib_handoff.c4`, relation sources are bare (`Handoff__CLI -> lib_handoff.Handoff__Document`) outside the module block. `build` exited 0, but `likec4 validate` was not run separately. Calls into core Ruby (`File.binwrite`) are not traced. This is known and documented. ## Reproduce n/a: this is a feature ticket. The dry run above is the evidence. ## Approach The shim, from the ADR-0300 owner sketch: ```ruby module UseCase def use_case(_name) = yield end Minitest::Test.include(UseCase) ``` Required work: 1. Add the UseCase shim — check: present `def use_case(_name) = yield` in `plugins/os/tests/test_helper.rb` 2. Wrap the handoff complete path — check: present `use_case('handoff complete')` in `plugins/os/tests/handoff/complete_test.rb` 3. Commit the generated journey view — check: present `dynamic view handoff_complete` in `plugins/os/design/generated/journeys/handoff_complete.c4` Orchestrator work: run `plugins/os-sdlc/bin/system-model build plugins/os`, then `likec4 validate`. Show Jared the view with `system-model serve plugins/os`. ## Acceptance criteria 1. Given the plugins/os suite, when it runs without the tracer, then it passes. 2. Given `plugins/os-sdlc/bin/system-model build plugins/os`, when it finishes, then `plugins/os/design/generated/journeys/handoff_complete.c4` holds the three messages above and `likec4 validate` accepts the model. 3. Given `system-model serve plugins/os`, when Jared opens the handoff_complete view, then he sees the three numbered messages. ## Owner sketch ```ruby module UseCase def use_case(_name) = yield end ``` ## Non-goals os-me journeys stay in #1392. Tracing calls into core Ruby is out of scope. ## Origin - Trigger: dry run of the #1327 tracer on `plugins/os` in this session. - Improvised this session: none. The dry run edits were not kept. - Chain: feature ← #1327 (tracer), ADR-0300; os-me journeys stay in #1392 - Root candidate: none found; searched journey, trace, use_case, system-model, handoff complete, dynamic view, plugins/os - Where: plugins/os/tests/test_helper.rb, plugins/os/tests/handoff/complete_test.rb - Session: 0bd25a72-f8ca-4331-a047-9cefdb9b0e3b - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os--claude-worktrees-fast-batch-15/0bd25a72-f8ca-4331-a047-9cefdb9b0e3b.jsonl

jared added the

labels

2026-10-26 14:18:19 +00:00

jared referenced this issue

2026-10-26 14:18:23 +00:00

Trace the os-backlog comment journey in plugins/os-backlog and build its site #1395

jared referenced this issue

2026-10-26 14:18:26 +00:00

Tag five os-me journey tests with use_case and record the operations.md proof #1392

jared commented

2026-10-26 14:18:51 +00:00

Author

Owner

Work started on branch ticket-1394 (worktree .claude/worktrees/ticket-1394) via /os-sdlc:implement, target os.

jared referenced this issue

2026-10-26 14:24:23 +00:00

behavior-verifier brief omits test_changes, producing a wrong fail and an unexpected_pass escalation #1111

jared commented

2026-10-26 14:24:28 +00:00

Author

Owner

Required work 2 check now uses single quotes to match Style/StringLiterals; the original double-quoted text conflicted with the repo's rubocop config.

jared commented

2026-10-26 14:25:32 +00:00

Author

Owner

Resolution

Done: Added the use_case shim to plugins/os/tests/test_helper.rb, wrapped the handoff complete path in complete_test.rb, generated and committed the plugins/os design model with the handoff_complete journey (3 messages), ignored built sites. Hand-finished after implementation 168 failed at behavior-verifier (test-only diff; occurrence on #1111).

Evidence: Commits 7fd1bba3, 2bd4ac74, 5bc91fbf on ticket-1394. Suite: 47 runs, 174 assertions, 0 failures. Rubocop: no offenses. likec4 validate: Valid (6 files). Design audit (opus): no findings.

Follow-ups: #1395 (os-backlog comment journey) is next. #1111 carries the verifier defect occurrence. No new follow-ups.

## Resolution **Done:** Added the use_case shim to plugins/os/tests/test_helper.rb, wrapped the handoff complete path in complete_test.rb, generated and committed the plugins/os design model with the handoff_complete journey (3 messages), ignored built sites. Hand-finished after implementation 168 failed at behavior-verifier (test-only diff; occurrence on #1111). **Evidence:** Commits 7fd1bba3, 2bd4ac74, 5bc91fbf on ticket-1394. Suite: 47 runs, 174 assertions, 0 failures. Rubocop: no offenses. likec4 validate: Valid (6 files). Design audit (opus): no findings. **Follow-ups:** #1395 (os-backlog comment journey) is next. #1111 carries the verifier defect occurrence. No new follow-ups.

jared closed this issue

2026-10-26 14:25:32 +00:00

jared referenced this issue from a commit

2026-10-26 14:26:32 +00:00

feat(os): trace the handoff complete journey and build the plugins/os site (#1394)

jared referenced this issue from a commit

2026-10-26 14:26:32 +00:00

chore: ignore built LikeC4 sites under plugins/*/design/site (#1394)

jared referenced this issue from a commit

2026-10-26 14:26:32 +00:00

docs(os-sdlc): system-model History row for #1394

~~jared referenced this issue 2026-10-26 15:08:34 +00:00~~