feat: expose structured Lavish feedback reads

[dnth]

Intent

Port upstream kunchenguid/firstmate PRs kunchenguid#3321 and kunchenguid#3371 into this fork on the firstmate side only, adapting bin/fm-procevent-lavish.sh. Present captured Lavish results as structured output enumerating every prompt and annotation, keeping the session-ending freeform message distinct. Always surface non-choice freeform comments even with selectors, while suppressing machine-generated choice Context data and not fabricating comments for pure annotations. Add executable behavioral regression coverage and keep bin/fm-lint.sh clean. Do not modify lavish-axi or any OMP adapter/spawn/verification/wake code; prove tests/fm-omp-harness.test.sh passes. Firstmate-Validation-Generation: 9fe6c20f313742c3baf00e7da620264e

What Changed

• Added a read command to present captured Lavish results with completeness metadata, per-item annotations, and a distinct session-ending message section.
• Preserved non-choice freeform comments while filtering machine-generated choice context and avoiding fabricated comments for pure annotations.
• Updated process-event guidance and added executable regression coverage for the structured-read behavior.

Risk Assessment

🚨 High: The requested two-PR port is incomplete, and the new reader can silently alter multiline feedback content, so merge requires explicit scope confirmation and a correctness fix.

Testing

Ran the targeted process-event/Lavish behavioral suite and required OMP harness regression suite; both passed. Manually exercised the public structured-read command and captured reviewer-visible transcript evidence. No source or worktree artifacts were left behind.

Evidence: Lavish structured-read evidence

Structured Lavish read transcript showing a distinct session-ending message, preserved selector-bearing freeform comment, pure annotation, filtered choice Context payload, and completeness metadata.

$ bin/fm-procevent-lavish.sh read <fixture>

SESSION-ENDING MESSAGE
| final captain comment
END SESSION-ENDING MESSAGE

declared_items: 4
presented_items: 4
malformed_items: 0
complete: yes
lifecycle: feedback
session_ended: true
annotation_count: 3
session_ending_message_count: 1

ANNOTATIONS
ANNOTATION 1 of 3
element_uid: el-a
element_selector: #a
tag: note
text:
| element text
prompt:
| typed comment
ANNOTATION 2 of 3
element_uid: el-b
element_selector: #b
tag: note
text:
| pure annotation
ANNOTATION 3 of 3
element_uid: 
element_selector: 
tag: choice
text:
| Ship it
END ANNOTATIONS
END LAVISH RESULT (4 of 4)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 2 issues (1 error, 1 warning)

• 🚨 bin/fm-procevent-lavish.sh:84 - The required intent says to “Port upstream kunchenguid/firstmate PRs fix(bin): present Lavish feedback as structured output kunchenguid/firstmate#3321 and fix: surface comments on Lavish annotations kunchenguid/firstmate#3371 into this fork on the firstmate side only.” This change only adds the fix: surface comments on Lavish annotations kunchenguid/firstmate#3371-style reader; the fix(bin): present Lavish feedback as structured output kunchenguid/firstmate#3321 firstmate-side behavior is absent: arm still registers raw lavish-axi poll (bin/fm-procevent-lavish.sh:84) and there are no poll, silent, or answers commands. Please confirm whether omitting those required PR3321 behaviors is intentional or complete the port.
• ⚠️ bin/fm-procevent-lavish.sh:193 - body filters out empty lines (grep { length }), so a captured comment or annotation such as first line\n\nsecond line is emitted as two adjacent lines and the original content is not preserved. This violates the structured reader's promise to present captured feedback faithfully; emit split lines while retaining interior blank lines (only trim an optional final terminator).

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-procevent.test.sh
• bash tests/fm-omp-harness.test.sh
• Manual bin/fm-procevent-lavish.sh read verification with representative feedback, annotation, choice, and session-ending message records; transcript saved as evidence

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.