new(process-map): process map that pins each question to the step it is about (draft at Stage 2 close, full at Stage 3)

[MendixMau]

new(process-map): process map that pins each question to the step it is about (draft at Stage 2 close, full at Stage 3)

Why

At Stage 3 a reviewer gets the open questions, the ASSUMED decisions and the wireframes as three separate lists. A business owner who reads "Should a rejected order go back to draft?" cannot tell where in the work that happens, so the question gets answered blind or not at all. In a requirements-driven rebuild POC (2026-10-16) the reviewer said exactly this: "I really don't understand where in the process they fit."

Name

"Process" in the progress report means the toolkit's own stages; this page shows the app's business process. Distinct names avoid the confusion, so it is the process map (renamed from "process board" after review). The progress report (separate PR #434) will link to it later; not in this PR.

Review fixes

• The fixture BRD is committed (tests/wave2/fixtures/process-map/brd/, read through brdDirs), so the suite passes on a clean checkout.
• Pass 1 works with no wireframes: a step may name a screen that is not drawn yet, or have none; a person step stays a person step (solid card), only system steps are dashed. Strict rules return once a wireframe exists. Tests added.
• Routing re-rendered; CHANGELOG ends with the credit and covers both passes; manifest row is optin with corrected line cites; a wireframe edit marks the map stale in the gate; the full-size screen link keeps the sandbox.

What

Two passes over one model. Pass 1 at Stage 2 close: right after the BRDs validate and the questions are consolidated, the map is drawn without screens, so each question is raised in its place in the work. It also feeds Stage 3: the processes and lanes inform module boundaries, the journeys and the screen list. Pass 2 at Stage 3: after the wireframes exist, only the script re-runs and the screens appear on the steps. The hand work happens once.

• skills/process-map.md: when to run it, how to author design/process-model.json (lanes per role, steps on wireframes, decisions, standalone use cases), how to anchor every item (derived first, judged with a basis for the rest, global buckets counted), build, and verify by looking at headless Chrome screenshots.
• project-bin/process-map.js (Node stdlib, deterministic) plus process-map.template.html:
  • validate [--strict]: a step page with no wireframe, a task without a page, an unknown use case, a use case on no process and not standalone, a decision with fewer than two outcomes, two steps in one cell, a broken next, a duplicate id. --strict also fails on unanchored items.
  • anchor: places items mechanically (named microflow, listed or named use case, named screen, overlapping source lines, a decision naming a placed question). Keeps judged entries by fingerprint, so a reworded question is unplaced again instead of silently wrong.
  • build: writes design/process-map.html. It is self-contained and offline. It opens light, and the Theme button switches the map and the screens together (a wireframe's own hard-coded theme is dropped). It has an index and one swimlane map per process. Each step shows a wireframe thumbnail. Pins are coloured by blocking, open or assumption. There is a "Blocking only" filter. Clicking a step opens a drawer with the large screen, a prototype link, the question cards and technical details behind a click. Field feedback was "I didn't know I had to click", so a how-to bar, an "N questions · Open ›" footer on every card and a pulse on the first step (until the first click) make the click targets obvious. Card screens render at 640px wide so text stays legible.
• Wiring:
  • Stage 2 Agent produces (pass 1) and Stage 3 Agent produces and Surface rows in conversion-runbook.md.
  • A process-map row in artifact-manifest.tsv (optin: an existing model counts as opting in).
  • design/process-model.json added to the swimlanes opt-in paths, because the map draws the same lanes.
  • A CAC-3 line (pass 1 shown with the questions) and a CAC-4 line (pass 2 walked at the Stage 3 gate close-out, which has no closing checkpoint).
  • A skill-routing.tsv row, rendered.
  • install-manifest.sh installs the generator and the template as a pair.
  • check_stage_3 FAILs when the model exists but the map does not, or when the map is older than its model, its anchors or any wireframe.
• tests/wave2/test-process-map.sh on a synthetic order approval fixture in tests/wave2/fixtures/process-map/.

Evidence

• Field run (customer data kept local, not in this PR): 9 processes, 73 steps, 110 use cases (6 standalone), 37 wireframes, 102 pinnable items: 48 derived, 54 judged (19 of them global), 0 unanchored. Index and maps checked by screenshot, light and dark.

• tests/wave2/test-process-map.sh: 74 ok, 0 FAIL on a clean checkout (fresh worktree), including pass 1 without screens and a committed synthetic BRD.

• Related suites still pass: closeout, wireframe-count, bug03-gates, bug06-freshness, surface-column, routing-tier, baseline-pack, render-routing, manifest-clean-checkout, prototype-links, assemble-prototype, runbook-slice (with LC_ALL=C).

• bin/render-routing.sh --check, bin/check-skill-routing.sh and bin/check-scripts.sh are clean. bin/check-no-client-data.sh is clean against the denylist.

• Pre-existing, unrelated: test-app-facts-db-uri (9 pass, 1 fail), test-app-restart (killed on its sleep) and test-runbook-slice (needs an argument) fail the same way on current master.

Not in this PR

• Making the map the front page of the Stage 2 surface (brd-report.html linking into it) is a follow-up.

• No Windows run yet. The script is Node stdlib only, and the gate addition uses the same -ot test as the blueprint check.

• The map does not yet feed journey-proof.md mechanically. Today the link is the same process names.

Reproduction test

A fresh Sonnet agent, given only the skill (then named process-board), rebuilt the map for a field project. Verdict: close. Structure and placement nearly the same; the process split differed because the reproduction gave the dashboard and the document export their own processes.

Measure	Reproduction	Field run
Processes	11	9
Steps	68	73
Use cases on steps	106	104
Standalone use cases	4	6
Items to pin	102	102
Derived	49	48
Judged (not global)	31	35
Global	22	19
Unanchored	0	0

• 14 of 18 sampled questions landed on the same or an equivalent step.
• About 25 tool calls and 10 minutes. validate --strict and build passed.
• The test found 12 gaps in the skill (fallback script path, anchor --json stdout, where judged entries go, second use case id example, standard global buckets, exit code 1 while items remain, Chrome flags, board width, wireframe layout sketches, dashboard and export rule, questions file path). The latest commit fixes them: new ignorePages option in process-model.json, anchor --json keeps stdout pure JSON, and a test case for both.

Advice: replace or front the BRD report. This needs to be decided by the main sessions.

The map could become the Stage 2 front page, or replace brd-report.html.

Replacing would need:

• the map to show more BRD detail: per-step use case text, rules, entities and acceptance criteria in the drawer, and links by BRD id;
• a plain per-BRD view kept for reviewers who read by capability;
• changes to the gate and manifest entries for brd-report.html.

Recommendation: front first (board as the entry, BRD report one click away). Replace only after a field review.

🤖 Generated with Claude Code

🤖 Generated with Claude Code