Stage 3 interaction model, part 1: skill + wireframe page contract + wiring (#291)

[MendixMau]

#291, part 1 of 3: skill and wiring

Depends on #315. This branch merges chore/baseline-word-trim (#315), which frees room in the baseline word budget. Merge #315 first; this diff will then shrink to this PR's own changes.

Problem

Stage 3 never asks three questions:

• where each role lands;
• how each role finds its work;
• which object each page is about, and who passes it to the page.

Wireframes get drawn as one role looking at one record, and every later check inherits that view. In three apps built with the toolkit, every gate passed:

• Stage 3 and Stage 4: PASS
• page fidelity: 81–89% on the affected pages
• lint: 0 errors
• e2e: 69/69

Meanwhile one of those apps had these defects:

• 8 pages were rooted on a parameterless "current record" retrieve;
• all 6 roles had the same home page;
• 3 of the 6 menu items were process stages.

A navigation review of a second app found 16 more defects of the same kinds.

Fix

New skill skills/interaction-model.md (on demand). It runs at Stage 3, after the role model is CONFIRMED and before the first wireframe, and produces design/interaction-model.md with:

• a home page per role;
• an inbox per BRD user task;
• an object hub for each object users follow over time;
• a per-page table: page | how reached | page parameter / context object | data view source | nav entry | role(s).

The skill also contains:

• Four rules for the table:
  1. A page about one object takes that object as its parameter.
  2. Every caller passes that object.
  3. Menu items are lists, inboxes or tools, never process stages.
  4. One main grid per page; sibling sets go in tabs.
• A failure-mode table, each row with a one-line bad example using generic names:
  • a page whose data comes from a parameterless "current/first" retrieve;
  • show page called without its argument;
  • home pages that don't match the design;
  • process stages in the menu;
  • a forced grid min-width;
  • read-only fields with no rendering specified;
  • a save that reopens its own page.
• A two-objects-two-roles walk before the Stage-3 ✋. It is a paper walk over the per-page table unless the wireframes actually draw two records.
• "Done when" criteria with denominators.

Wireframe page contract (skills/design-artifacts.md Step 3). Every wireframe now opens with a <div class="wf-contract"> block containing three lines:

• Page parameter:, written as Module.Entity or none — <reason>. The skill's per-page table uses exactly the same form, because a later gate will parse this line.
• Reached from:
• Drawn as role:

Because the block uses the wf- prefix, page-fidelity.js drops it as annotation and assemble-prototype.js hides it behind Show bindings.

Wiring:

• skills/design-artifacts.md:
  • new Step 2b, pointing to skills/interaction-model.md;
  • design/interaction-model.md added to the output tree.
• skills/conversion-runbook.md, Stage 3:
  • "Agent produces" now names design/interaction-model.md (first);
  • the Gate row adds "Interaction model walked with two objects, two roles."
• bin/lib/skill-routing.tsv: new row, on demand, stage 3, lead,ba,architect (ba runs the Stage-3 interviews), group design. The re-render changed these files:
  • README.md
  • ROUTING.md
  • the architect and ba agent stubs
  • the stage-3 entry in gate-check.sh stage_protocol_paths

Evidence

• The counts above come from the issue and its comments, cited without naming any app.
• I ran page-fidelity.js on tests/wave2/fixtures/page-fidelity-mocks/bind-contract.html twice: once as is and once with a wf-contract block injected. The output was byte-identical.

Risks

• Baseline word count (bin/render-routing.sh --check):

  State	Words (budget 80,000)
  master before chore(context): free baseline word budget without dropping rules #315	79,997
  master + chore(context): free baseline word budget without dropping rules #315 + this PR's first commit	76,262
  master + chore(context): free baseline word budget without dropping rules #315 + this PR	76,270

  The +8 words are the Gate-row clause.

• Protocol notice reaches every stage: projects will be told the protocol changed once they sync. skills/interaction-model.md is added to the Stage-3 protocol paths. More importantly, conversion-runbook.md changed, and it is always relevant, so projects at any stage see the notice. That is intended: the runbook text changed.

• No other behaviour change for existing projects: there is no new gate or blocking check yet.

Checks run

Check	Result
bin/check-scripts.sh	rc 0
bin/render-routing.sh --check	in sync
bin/check-portability.sh	rc 0
bin/check-no-private-citations.sh	rc 0
bin/check-pr-discipline.sh origin/master	rc 0
LEAKGUARD_ALLOW_NO_DENYLIST=1 bin/check-no-client-data.sh	rc 0
Forbidden-term grep over added lines	0 hits

No fixture is included because no instrument changed. By inspection, the existing fixtures that mention the touched skills don't assert on the changed text.

Flake seen in render-routing.sh --check: twice it reported a random, actually routed skill (learned-microflow-patterns.md, then module-brief.md) as UNROUTED, with rc 2. Repeat runs passed. The two reported files are unrelated to this change, so it looks pre-existing.

Field-run status

Still owed. The skill has not yet been used on a real project's Stage 3.

Design for the follow-ups (not in this PR)

Part 2: Stage-3 gate facts (bin/gate-check.sh <p> 3, facts only). This also needs an artifact-manifest row for design/interaction-model.md (bin/lib/artifact-manifest.tsv, with Stage-3 consumers cited), so that a missing artifact reports PENDING out loud.

The gate reports PENDING when the artifact is absent, and FAIL when:

• a role in the role model has no row in the Role homes table;
• a BRD user task or approval has no inbox row and no stated reason;
• a design/wireframes/*.html file has no Page parameter: line inside a wf-contract block, or the line matches neither Module.Entity nor none — <reason>.

These findings are waivable in the register. Projects already past an --adopt point report ADOPTED. checkpoint-design.md also gains a question, "who lands where, and how does each role find its work", asked alongside the layout question. Fixtures will be synthetic project trees, each failing on master.

Part 3: model-side check (Stage 5; a project-bin script or lint rules). It reads describe navigation, page data views and show page calls, then reports:

• home pages per role compared with the artifact;
• pages whose root data view is a parameterless microflow retrieving first from an entity that is not a singleton;
• show page P with no argument, where P takes an object;
• menu items whose target is a stage page or a page that takes a parameter;
• optionally, a fixed min-width on grid selectors in the theme.

Its test input must be captured describe output from a real model, never hand-written. The acceptance target from the issue: on the affected app it reports at least 8 current-object pages, 1 home for 6 roles, and 3 stage menu items.

Journey and seed changes belong to testing-shape.md and journey-proof.md, which other PRs own. Those changes are 2+ open objects, and one journey per non-primary role starting at its home.

Refs #291

🤖 Generated with Claude Code

https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw

[MendixMau]

Landed on master as part of the integration squash #329 (commit 31e90ae), after independent review — its Review: line is in that commit message. Closing as superseded.

---

Generated by Claude Code