crewli/dev-docs/FORM_BUILDER_SCOPE_POLICY.md

# Form Builder — Scope Discipline Policy

**Status:** Guidance policy. Applies to all Form Builder and adjacent
module work in Crewli until explicitly superseded.

## Context

April 2026: analysis of ~60 practical form use cases against the
current Form Builder architecture confirmed that the polymorphic
owner/subject model, the 17 field types, and the event-listener
integration pattern form a generic foundation that scales. Of the
60 use cases surveyed, ~70% fit the existing architecture with
incremental work (new listener or new field type per use case), and
~19% require separate domain architectures outside the Form Builder.

**This is reassurance, not a work order.** The full coverage of 60
use cases represents 4-5 months of fulltime solo work. Bert's actual
near-term needs — his own volunteer organisation plus the first
handful of potential SaaS customers — are estimated at 5-8 concrete
form types, not 60.

## Policy

### 1. No speculative purpose-specific work

Do not build listeners, field types, purpose enum values, or UI
flows for form purposes that no current user (Bert's own
organisation or a named prospect) has concretely requested.

This explicitly includes:

- Artist advance module — defer until a festival with real tech
  riders needs it
- Supplier intake module — defer until a supplier-intensive event
  is in the pipeline
- Post-event evaluation module — defer until Bert's own event
  actually finishes and needs retrospective tooling
- Compliance flows (W9, insurance claims, GDPR workflows beyond
  existing ARCH §13) — these are separate projects, not Form
  Builder features
- Real-time operational forms (meal tickets, inventory counts,
  live capacity) — these belong to dedicated modules (check-in,
  inventory), not Form Builder

Any prompt that asks to extend the Form Builder for one of these
should be questioned back to Bert with: "Do you have a concrete
user who needs this in the next 8 weeks, or is this speculative?"

### 2. One architectural exception: polymorphic subject picker in S3b

The organiser-facing form creation UI in S3b must include a
subject-type picker (dropdown or equivalent) that writes to
`form_schemas.subject_type` when configured, even though only
`person` is functionally wired in S3b.

Options to surface in the picker:

- Vrijwilliger / deelnemer (subject_type='person') — functional
- Artiest (subject_type='artist') — disabled / "binnenkort beschikbaar"
- Leverancier (subject_type='company') — disabled / "binnenkort beschikbaar"
- Anoniem publiek (subject_type=null) — functional for PUBLIC_COMPLAINT / PUBLIC_RSVP / POST_EVENT_EVALUATION

**Why this is the exception:** retrofitting a subject-type picker
later requires touching the create/edit/list views, the schema
configuration form, the binding config UI, and the sibling-endpoint
logic — days of rework. Building the UI shell with disabled options
now is ~2 extra hours in S3b and eliminates that future refactor.

This is the only forward-looking architectural investment permitted
without a concrete user request.

### 3. Economic triggers for future Form Builder expansion

Unlock categories of work only when one of these signals fires:

| Expansion | Trigger |
|---|---|
| FILE_UPLOAD + IMAGE_UPLOAD + SIGNATURE field types | A required form (VOG upload, minor consent, press accreditation) has a concrete submitter waiting |
| Artist advance module | A festival with >3 booked artists needs digital tech riders |
| Supplier intake module | An event has >3 suppliers where paper/email intake has become painful |
| New purpose enum value | A concrete form use case requires it AND that use case has a named user |
| Shift-swap request flow | Volunteers have asked for it twice in production |

Explicitly do NOT unlock expansions because:

- The architecture supports it elegantly
- It would be "nice to have"
- A competitor has it
- It appears on an aspirational feature list

### 4. When reviewing prompts for Form Builder work

If a prompt asks Claude Code to extend the Form Builder in ways
not justified by a concrete user or by the S3b subject-picker
exception above, push back before implementing. Ask Bert:

1. Which concrete user needs this in the next 8 weeks?
2. Is there a simpler path (manual admin action, existing UI,
   out-of-scope) that would work for now?
3. If we defer this 6 months, what actually breaks?

Proceed only when answers are concrete (named person / event /
deadline), not hypothetical ("a customer might want this").

### 5. Where this policy does NOT apply

This policy scopes Form Builder and its direct integrations. It
does NOT apply to:

- The S3b organiser UI itself (build it well, it unlocks Category A
  use cases immediately)
- Bug fixes and polish on shipped Form Builder features
- Documentation of existing behaviour
- Refactors that reduce technical debt in already-shipped code
- Unrelated modules (check-in, accreditation, briefings,
  communication, production) — those have their own prioritisation

### 6. Record of decisions

When this policy causes a feature to be deferred, record it briefly
in `/dev-docs/BACKLOG.md` with the trigger that would unblock it.
This keeps the deferred list visible without pretending it's
actionable today.

## Closing note for Claude Chat

If planning work that would touch Form Builder scope beyond this
policy, flag it at the start of the session: "This touches
scope-deferred Form Builder work; confirming trigger before
proceeding." Then wait for Bert's confirmation. This is a
discipline guardrail, not a veto — but the default answer is "not
yet" until a concrete trigger exists.