Stage 3 interaction model, part 2: gate facts + artifact manifest (#291)

[MendixMau]

Direct lane

Review status. An independent review returned MERGE-AFTER-FIX. The fixes are in commit c236e62; see "Changes after review" below.

What changed and why (one paragraph):
Part 1 (#317) added skills/interaction-model.md and the wireframe wf-contract block, but nothing yet noticed when the artifact was missing or incomplete. This PR adds the facts half and leaves judgement in the skill.

• Manifest row. bin/lib/artifact-manifest.tsv gains an interaction-model row (stage 3, report-only). If design/interaction-model.md is missing, the artifact check reports it PENDING out loud. This does not block.
• New check, run once the file exists. bin/lib/interaction-model-check.sh is sourced by gate-check.sh after the artifact block. Its findings print under Interaction model (stage 3 facts): with denominators:
  • (b) FAIL: a BRD approval, review, sign-off or user-task use case that is not named on any line under an "Inbox" heading. A table row or a bullet both count.
  • (c) FAIL: a design/wireframes/*.html whose wf-contract block has no valid Page parameter: line.
  • (a) MANUAL, never FAIL: a BRD actor with no "Role homes" row. BRD actors are not the confirmed role model, so the check asks a person to confirm instead of failing.
• Effect on Stage 3. check_stage_3 turns any un-waived FAIL into a Stage-3 FAIL. If the only open findings are MANUAL ones, Stage 3 is MANUAL (exit 2).
• checkpoint-design.md gains Q1b, "who lands where, and how does each role find its work", asked next to the layout question.
• brd-to-build-plan.md Step 7 gets one sentence telling the build plan to read its wire points from the artifact. Without it, the manifest row's build-plan consumer would be a false citation.

Changes after review (c236e62):

1. Inbox coverage. Any line under an "Inbox" heading covers a task: a table row, a - or * bullet, or a numbered item. The skill's own Step 2 writes inboxes as bullets.

2. Roles. A BRD actor with no Role homes row is now MANUAL. The message names the actor and says: confirm it is a user role, or add a | <actor> | none — <reason> | row (system actor / merged into another role). A none — <reason> row counts as covered.

3. Which use cases count as tasks. A use case is checked only when:

   • its title starts with approve, review or sign-off / sign off (case-insensitive, after an optional id prefix such as UC013:); or
   • its title contains "user task"; or
   • its mdlRefs names a user task.

   "View approval history", "Configure approval thresholds" and "Disapprove…" no longer FAIL, and fixture cases assert that.

4. Wireframe parser.

   • Inline tags are stripped before matching, so <b>Page parameter:</b> Sales.Order and <code>Sales.Order</code> read.
   • The end of the wf-contract block is found by counting <div> depth, not by taking the first </div>.
   • The separator in none — <reason> may be a hyphen, an en dash or an em dash, and HTML entities for the dashes are decoded.
   • CRLF files read the same as LF files.

5. Projects that write the interaction model mid-build. The Stage-3 check runs again on every gate run. A project that writes design/interaction-model.md during the build therefore gets one FAIL per wireframe drawn before the model existed. That is intended. The FAIL output now ends with one remedy line: add <p>Page parameter: …</p> to the wireframe's wf-contract block, or waive that wireframe with Waived artifact interaction-model/<file>.html: <reason>.

Ambiguities, resolved narrowly:

• Where roles come from. No bin/ script reads a role model from PROJECT.md. The only role list any bin/ script reads is the BRD top-level actors, in bin/brd-report.sh, so that is the source. Because it is not the confirmed role model, a missing actor is MANUAL only.
• Which heading counts. Role homes are read from the table under a heading containing "Role homes", with columns found by the header names Role and Home page. Inbox lines are any lines under a heading containing "Inbox".
• Id matching. Use-case ids repeat across BRDs, so a mention of UC002 covers that id in every BRD. Waivers and FAIL lines use <BRD id>/<UC id>.
• Which wireframes. Only top-level design/wireframes/*.html, the glob as written.
• Waiver syntax. No new flag.
  • Waived artifact interaction-model: … waives the whole artifact. This is the artifact check's existing hand-written line.
  • Waived artifact interaction-model/<unit>: … waives one finding. The unit is an actor name, <BRD>/<UC>, or a wireframe file name.
  • Waived stage 3 does not hide these FAILs, which is consistent with waiver_applies.
• Projects adopted above stage 3 report ADOPTED and get no findings.
• A missing artifact is report-only PENDING, not a FAIL. This follows the part-2 design rather than the issue's acceptance criterion 4, so projects already past Stage 3 are not suddenly blocked.

Field evidence: none yet. This has run only on synthetic project trees, including the independent reviewer's probe trees, reproduced as fixture cases T3c and T9–T12. A field run is still owed on a real project the maintainer chooses.

• No client data anywhere in the diff

• Size cap: within cap, excluding the fixture and CHANGELOG

• Test tier: fixture level, on synthetic trees. tests/wave2/test-interaction-model-gate.sh results:

  gate-check version	Passed	Failed
  base branch	19	25
  previous head 986f4e7	27	17
  head c236e62	44	0

  Existing fixtures on head, all with 0 failed:

  Fixture	Passed
  test-bug03-gates.sh	31
  test-source-sufficiency-gate.sh	7
  test-source-ledger.sh	55
  test-closeout.sh	34
  test-wrong-verdicts.sh	20
  test-wireframe-count.sh	5

• New instrument, golden input: synthetic, built from the skill shapes and the reviewer's probes, not captured from a real project.

  • Layouts: both covered, single-tree and nested analysis/<name>/.
  • Platform: bash 3.2-safe; uses jq, which gate-check already requires; no mac-only tools; CRLF covered. Not run on Git Bash.

• CHANGELOG line, credited "field retro (Usability/flow defects pass every gate: proposal for a Stage-3 interaction-model deliverable and gate #291)"

Checks run (head c236e62): all exit 0.

• bin/render-routing.sh --check: in sync. Baseline is 74,959 words before and after; checkpoint-design.md is not in the always-on set.
• bin/check-scripts.sh
• bin/check-portability.sh
• LEAKGUARD_ALLOW_NO_DENYLIST=1 bin/check-no-client-data.sh
• bin/check-pr-discipline.sh origin/integration/2026-10-14
• Forbidden-term grep over added lines: 0 hits.

Risks:

• A project that already has design/interaction-model.md can turn red at Stage 3. A project that writes it mid-build gets one FAIL per legacy wireframe, with the remedy line shown above.
• An actor with no home makes Stage 3 MANUAL (exit 2) until someone confirms it or adds a none — <reason> row.
• Changing brd-to-build-plan.md and checkpoint-design.md triggers the protocol-changed notice at stages 3 and 4.

Refs #291

🤖 Generated with Claude Code

https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw

[MendixMau]

Superseded by #333: the same two commits, replayed onto master after #329 squash-merged. The review history is carried over in #333's body.

---

Generated by Claude Code