Rework challenge 01, and fix defects found walking the lab

[nadvolod]

Follow-up to #9, reworking challenge 01 and fixing defects found while walking the lab. Everything here is already published to Instruqt and verified in a running sandbox.

Challenge 01 now goes: run it, see it, understand the shape, then read the code

Old order sent learners from the starter output straight into source. New order:

Run Three Payments → See It in the Temporal UI → Review the Monolith Architecture → Find the Coupling → See the Empty Namespace

The UI section lands on payments-namespace, gives a Workflow ID table, and opens payment-TXN-C to read its result:

{ "success": false, "status": "DECLINED_COMPLIANCE", "riskLevel": "HIGH", "error": null }

success is false, error is null, and the Workflow is Completed. That distinction is worth planting in challenge 01, because challenge 04 sends the same result across a team boundary and it should look identical: a declined payment is a business outcome, a failed Workflow is a defect.

The diagram section points at step 5 of 8 (the arrow crossing team zones inside one process) and step 8 of 8 (Compliance owning an empty Namespace).

Find the Coupling now shows both register lines rather than describing them, so nobody has to guess which two lines put two teams in one process.

Defects fixed

A run of = desynchronises Instruqt's renderer. The Compliance Worker's startup banner was in a bash,nocopy fence. The opening fence and the leading ==== line were swallowed into a collapsible divider; the trailing ==== then formed a setext <h1> from the two lines above it; every fence after that point was off by one, so the closing fence opened a code block that ate several paragraphs of prose and rendered the next ```bash,nocopy marker as literal text.

The raw markdown was correct and instruqt track validate passed, so nothing caught it. Nine other nocopy fences in the same track render fine. Replaced with one realistic output block: the Gradle task line, the stubs line, all three MultiThreadedPoller lines, and the banner text without its separators. That also removed a duplicate showing the Nexus Poller line twice.

Challenge 04 told learners to look for a banner they never write. The exercise's println is hardcoded to the monolith text, so a learner who completes the Endpoint mapping correctly still reads ComplianceActivity (monolith, will decouple). The assignment claimed a Nexus line replaced it. The verification step immediately after the hardest edit in the lab would have contradicted itself. Now the assignment says the banner is stale text and the proof comes from the run. Challenge 01 still references that banner, correctly, because there the coupling really is written down in it.

.dockerignore shipped bin/ anyway. A bare bin/ matches only <context>/bin, not decouple-monolith/exercise/bin, so the image carried a stale second copy of every .kt file including old TODO text. Fixed with **/. Context transfer went 54kB to 11kB.

Text the code already said

Per the "let the code guide the TODOs" convention:

• Challenge 02 lost One Rule That Bites entirely. TODO 3 already explains that the runtime validates every method at Worker startup and names the exact Missing @Operation annotation failure.
• Challenge 03 lost the checkCompliance-slow / submitReview-fast explanation, which was TODO 5 and TODO 6 nearly line for line, and A Worker only handles work it has been told about, which was TODO 7's opening sentence verbatim. Body dropped 809 to 507 words.
• PaymentsWorkerApp.kt TODOs 10 and 11 became one short TODO 10, file 102 lines to 81. The comment is operational only; the reasoning lives in the assignment once. Exercise TODOs are now 1 to 10.
• Removed The annotation lives in io.nexusrpc. from TODO 1 and the editor-has-no-autocomplete aside from TODO 7.

Diagram

• The step 2 edge label ran over node text on both sides: ~300px of centred text in a 70px gutter. Edge labels now wrap on \n and that one is two short lines. The boundary wording was already in the step 5 caption.
• The Task Queue was only in the click-to-open detail panel. It now sits on the dashed process band, which wraps both team zones, so the outline containing both teams' code is the thing labeled with one queue.

Other

Event history types are written the way the UI writes them: Activity Task Scheduled, not ActivityTaskScheduled. A learner told to find the camel-case string is scanning for something that is not on screen.

Maintenance mode is off, so attendees can launch the track. Note that instruqt track push drops maintenance: false from the file because its serializer omits false values, so the off state is an absent key rather than an explicit false.

INSTRUQT.md gained the = trap with a pre-publish grep, the assignment-wording rules, and the note that a long edge label silently covers node text because the two render in different layers.

Verification

• Sandbox pinned at 0896ac82, linux/amd64. Verified inside the running image: one TODO marker in PaymentsWorkerApp.kt, no TODO 11, 81 lines, three uncommented registration lines intact so challenge 01 still runs the monolith, both comment removals present, diagram fixes present, bin/ gone.
• Both Kotlin trees compile.
• instruqt track validate clean; no = runs anywhere; every tab button verified by label rather than index arithmetic.
• Live track matches this branch (instruqt track pull reports up to date).

Not verified by eye and worth a look after merge: the wrapped step-2 label on the Monolith Architecture tab. That fix is arithmetic against the gutter width, not observation.

This branch never modified .github/, so the merge keeps main's CI fix from #10.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This pull request updates the Kotlin Nexus “decouple-a-monolith” Instruqt track content to reflect a reordered learning flow for challenge 01 (run → observe in UI → review architecture → read code), fixes several track-rendering and packaging defects encountered during lab walkthrough, and refreshes supporting documentation/diagram presentation.

Changes:

• Reworked Instruqt challenge assignments (especially challenge 01) to emphasize observing behavior in Temporal UI and the architecture diagram before diving into source.
• Fixed track correctness/operability issues (maintenance mode behavior, sandbox digest repin, .dockerignore to exclude build outputs, UI event naming alignment).
• Improved the monolith architecture diagram labeling (task queue emphasis + wrapped edge labels) and consolidated/cleaned exercise TODO guidance.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Updates Kotlin track structure/docs, tab count, ports, and maintenance-mode guidance.
kotlin/instruqt/track.yml	Removes maintenance: true and updates checksum after track changes.
kotlin/instruqt/config.yml	Re-pins the sandbox image digest; confirms ports include 8090 for the diagram tab.
kotlin/instruqt/01-run-the-monolith/assignment.md	Reorders and expands challenge 01 to include Temporal UI + architecture diagram first.
kotlin/instruqt/02-the-shared-contract/assignment.md	Removes duplicated guidance now covered by code TODOs.
kotlin/instruqt/03-the-compliance-side/assignment.md	Simplifies narrative, replaces problematic ==== banner output, and emphasizes proof signals.
kotlin/instruqt/04-the-payments-side/assignment.md	Updates directions around endpoint mapping/decoupling and corrects banner expectations.
kotlin/instruqt/05-durability-and-human-review/assignment.md	Aligns event-history naming with Temporal UI wording.
kotlin/diagrams/monolith-architecture.html	Improves process-band labeling (task queue) and wraps long edge labels to avoid overlap.
kotlin/decouple-monolith/exercise/src/main/kotlin/shared/nexus/ComplianceNexusService.kt	Refines TODO wording (removes redundant annotation package mention).
kotlin/decouple-monolith/exercise/src/main/kotlin/payments/temporal/PaymentsWorkerApp.kt	Consolidates TODO guidance (TODO 10/11 → TODO 10) and clarifies endpoint mapping vs decoupling edits.
kotlin/decouple-monolith/exercise/src/main/kotlin/compliance/temporal/ComplianceWorkerApp.kt	Trims non-essential commentary in TODO guidance.
kotlin/.dockerignore	Ensures build outputs like **/bin/ don’t get baked into the sandbox image context.
INSTRUQT.md	Documents renderer traps, assignment-wording rules, and diagram constraints for future maintenance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.