docs(approval-gate): mark role/quorum fields as advisory; runtime warns when set

[aziolek]

Summary

Aligns the approval-gate documentation and schema descriptions with what the runtime actually enforces. Adds a console.warn (once per gate at store init) when a document declares allowedRoles, requiredApprovers > 1, or requireReason: true, pointing embedders at the security-model section of the component catalog.

No behaviour change beyond the new warning.

Motivation

The current docs describe the approval-gate's allowedRoles / requiredApprovers / requireReason fields as enforced controls. Reading the runtime, they are not:

1. packages/renderer-react/src/components/ApprovalGateRenderer.tsx:30-49 dispatches APPROVAL_GRANTED with a hardcoded actor: { id: 'current-user' } straight to store.dispatch, bypassing approvalGateHandler.onAction. The handler's ctx.policy.enforce('approval_grant') is therefore unreachable from the UI.
2. packages/runtime/src/core/document-store.ts:194-201 handles APPROVAL_GRANTED by setting status: 'approved' and writing the actor into bindings, without invoking policy.enforce, without consulting allowedRoles / requiredApprovers / requireReason, and without validating the actor.
3. packages/runtime/src/core/document-store.ts:20 accepts options.registry?: AttachableRegistry but the function body never reads it (compare options.sessionId, options.documentId, options.environment, options.policy, all of which are read).
4. ButtonRenderer, FormRenderer, and WebhookRenderer do not read componentState.disabled / componentState.visible, so even a disabled: "{{gate.status}}" binding wouldn't prevent a downstream action from firing.

packages/runtime/tests/document-store.test.ts:150 codifies the current behaviour as the desired contract — a direct store.dispatch({ type: 'APPROVAL_GRANTED', componentId: 'gate1', actor: { id: 'user-1', role: 'manager' } }) flips status to 'approved' against a gate that has no role/quorum constraints, with no assertion that any policy check ran.

There are two coherent ways to address this. This PR is the smaller of the two — make the docs honest. The larger alternative is to add a host-identity API and wire approvalGateHandler.onAction into dispatch; that requires an API surface decision (where verified identity comes from) that this PR doesn't preempt.

Changes

1. packages/spec/src/schemas/components/approval-gate.ts — add .describe() text on requiredApprovers, allowedRoles, requireReason marking them advisory.
2. packages/runtime/src/core/document-store.ts — add warnIfAdvisoryApprovalFields(comp) helper, called from the init loop and from updateAst's new-component branch. Emits console.warn once per gate the first time it enters the store.
3. docs/reference/component-catalog.md — drop "Supports role-based access control" from the section opener; add an "Important — security model" callout above the property table explaining the trust boundary; update the field table to mark the three fields advisory; rewrite the example description to drop the "SOX compliance requirement" framing.
4. docs/guides/creating-blueprints.md — change two "Approval gate enforces … role" checklist items to "declares" with a note that the host application enforces.
5. docs/guides/creating-documents.md — add advisory callouts after the two approval-gate examples (the manager-gate visibility example and the compliance-approval example).
6. docs/guides/enterprise-features.md — annotate the "Putting It All Together" example: the // 3. Create store with policy enforcement comment now notes that policy enforcement currently applies to the webhook (webhook_call) only, and points at the approval-gate security model.

Out of scope (happy to follow up)

1. Wiring approval-gate-handler into document-store's dispatch path. Requires deciding how the host injects a verified actor identity (proposed shape: MdmaProvider currentUser={{id, role}} flowing into AttachableContext).
2. Per-blueprint compliance claims in blueprints/change-management, blueprints/clinical-ops, blueprints/kyc-case, blueprints/incident-triage, blueprints/customer-escalation. Their manifests/READMEs name the approval-gate as the implementation of specific controls (SOX 404, clinical-staff restriction, etc.). Those edits probably warrant the maintainers' judgement.
3. SECURITY.md's in-scope list, which currently classifies approval-gate bypass as a reportable vulnerability — that classification only fits a runtime that ships enforcement.
4. Prompt-pack author guidance (packages/prompt-pack/src/prompts/mdma-author/_shared.ts) that tells the LLM these fields restrict approvers. Should track whatever (1) decides.

Disclosure note

SECURITY.md asks for private disclosure of approval-gate bypass via open-source@mobilereality.pl. This PR addresses only the documentation/schema-description side and intentionally does not disclose anything not already readable in the public source. If you'd prefer to handle the conversation about (1) — wiring real enforcement — privately first, I'm happy to email and treat (2)/(3)/(4) as follow-ups gated on that decision.

[gitsad]

@aziolek thanks for raising this. Yes, definitely you are right. MDMA's role is not to verify any app data that can be handled via approval-gate but for sure it should be passed through to be able to be handled by other functions. Looking forward to next PR or just let me know then I will provide necessary fixes related to this element.

[gitsad]

changed target branch to fix/approval-gates

[gitsad]

build failed in workflow

[aziolek]

build failed in workflow

Should pass now.