portal/plans/building-permits.yaml

# A building authority, written by hand to find where the plan language
# stops. 14 needs, 7 roles, 12 buckets, two needs sharing a bucket in
# each direction (public and internal), a decision no case officer may
# sign, a group outside the building that moves records and nothing
# else, a stage a deadline moves rather than a person, and four things
# the plan language cannot say at all - each named in the run's README
# rather than smuggled past.
business: Vestmark kommune - Building and Planning
language: en
contact: { name: Solveig Hauge, email: byggesak@vestmark.example }
mail: { from: "Vestmark Building and Planning <byggesak@vestmark.example>", reply_to: byggesak@vestmark.example }
about: >
  The building authority for twenty-one thousand people. Anything built,
  demolished, divided or changed in use is decided here: the drawings are
  checked against the zoning map, the neighbours and the other
  authorities have their say, and then the head of section signs. The
  same office inspects what is actually built, signs off finished work,
  and deals with building nobody applied for.

# Two features, two roles, no button. The authority exists for the
# person who wants to build; the next one it serves is the neighbour
# who finds out what is planned next door. Both have a move of their
# own after sending: the applicant withdraws, the objector withdraws,
# and both buckets are open to read.
does:
  - id: we-decide-what-may-be-built
    for: small-works-application
    text: >
      Everything built in Vestmark is decided here. You send the drawings,
      the neighbours and the road, fire and heritage authorities are heard,
      and you get a written decision you can hold us to.
  - id: your-neighbours-case-is-readable
    for: objection
    text: >
      If a notice landed in your postbox, the case behind it is open to
      read here, and what you write to us has to be answered by name in
      the decision.

doors:
  - id: want-to-build
    who: an owner or a firm with something to build, divide or change
  - id: building-near-me
    who: someone who lives next to what is being built

groups:
  - { id: front_desk, label: Front desk }
  - { id: case_officers, label: Case officers }
  - { id: section_head, label: Head of section }
  - { id: inspectors, label: Inspectors }
  - { id: appeals_board, label: Appeals board, invited_by: [section_head] }
  - { id: agencies, label: Hearing bodies, invited_by: [case_officers, section_head] }
  - { id: approved_firms, label: Approved firms, invited_by: [section_head] }
invites_by: [section_head, case_officers]

needs:
  # --- the public: something they want to build ----------------------
  - id: pre-application-meeting
    door: want-to-build
    who: someone with an idea for a building and no drawings yet
    wants: to hear what we will allow before paying an architect
    lands_in: meetings
    handled_by: case_officers
    stages: [open, scheduled, met, advised, cancelled]
    done_when: [advised, cancelled]
    success: [advised]
    # They can call it off themselves; the front desk does it when they ring.
    moves_by: { cancelled: [submitter, front_desk] }
    watched_by: [front_desk]
    mails: { open: submitter, scheduled: submitter, advised: submitter }
    stages_text: { met: we have met, advised: written advice sent }
    max_fields: 5
    collects:
      - { name: name }
      - { name: email, type: email }
      - { name: property_address }
      - { name: what_you_want, type: textarea }
      - { name: phone, type: tel, optional: true }
      - { name: site, type: location, optional: true }

  - id: small-works-application
    door: want-to-build
    who: an owner applying for something small enough to file themselves
    wants: permission to build it, and to know where the case stands
    lands_in: applications
    handled_by: case_officers
    stages: [open, incomplete, complete, on_hearing, recommended, approved, approved_with_conditions, refused, withdrawn]
    done_when: [approved, approved_with_conditions, refused, withdrawn]
    success: [approved, approved_with_conditions]
    skippable: [incomplete]
    # A case is sent back for the drawing it was missing, and the
    # hearing turns things up that send it back again. It may be
    # withdrawn from anywhere, and refused only once we have seen
    # everything: not on the day it arrives.
    reached_from:
      incomplete: [open, complete, on_hearing]
      refused: [complete, on_hearing, recommended]
    # No case officer signs their own case: only the head of section
    # moves one into a decision. The applicant answers a request for
    # missing papers, and may withdraw right up to the signature.
    moves_by:
      complete: [submitter, case_officers]
      approved: [section_head]
      approved_with_conditions: [section_head]
      refused: [section_head]
      withdrawn: [submitter]
    watched_by: [public, front_desk, inspectors, section_head]
    mails:
      open: submitter
      incomplete: submitter
      on_hearing: submitter
      approved: submitter
      approved_with_conditions: submitter
      refused: submitter
    stages_text:
      incomplete: papers missing
      complete: papers complete
      on_hearing: out to the neighbours and the agencies
      recommended: recommendation written
      approved_with_conditions: approved on conditions
    max_fields: 6
    collects:
      - { name: email, type: email }
      - { name: property_address }
      - { name: property_number }
      - { name: what_is_planned, type: textarea }
      - { name: neighbours_notified, type: select, options: ["Yes", Not yet] }
      - { name: site, type: location, optional: true }
      - { name: drawings_url, optional: true }

  - id: exemption-request
    door: want-to-build
    who: someone whose plans break a rule in the zoning map
    wants: to be allowed it anyway, with reasons on the record
    requires: An application already with us, and the case number from its receipt.
    lands_in: exemptions
    handled_by: case_officers
    stages: [open, county_asked, county_answered, recommended, granted, denied, withdrawn]
    done_when: [granted, denied, withdrawn]
    success: [granted]
    # The county answers from outside the building; nothing may be
    # granted before it has. The head of section signs, as for a permit.
    moves_by:
      county_answered: [agencies]
      granted: [section_head]
      denied: [section_head]
      withdrawn: [submitter]
    watched_by: [public, section_head]
    mails: { open: submitter, county_asked: submitter, granted: submitter, denied: submitter }
    stages_text: { county_asked: with the county, county_answered: the county has answered }
    max_fields: 4
    collects:
      - { name: email, type: email }
      - { name: case_number }
      - { name: which_rule }
      - { name: why_it_should_be_allowed, type: textarea }
      - { name: site, type: location, optional: true }

  - id: completion-request
    door: want-to-build
    who: an owner or firm whose building work is finished
    wants: the certificate that lets the building be used
    requires: A case number, and the work finished or close enough to move in.
    lands_in: completions
    handled_by: case_officers
    stages: [open, checked, temporary_permission, certificate_issued, refused]
    done_when: [certificate_issued, refused]
    success: [certificate_issued]
    # Most go straight through; the ones who want to move in before the
    # last of it is done detour past a temporary permission.
    skippable: [temporary_permission]
    moves_by:
      temporary_permission: [section_head]
      certificate_issued: [section_head]
      refused: [section_head]
    watched_by: [public, inspectors]
    turned_down_from: [open, checked]
    mails: { open: submitter, temporary_permission: submitter, certificate_issued: submitter, refused: submitter }
    stages_text: { checked: checked against the inspections, temporary_permission: temporary permission to use, certificate_issued: certificate issued }
    max_fields: 5
    collects:
      - { name: email, type: email }
      - { name: case_number }
      - { name: property_address }
      - { name: work_finished, type: date }
      - { name: asking_for, type: select, options: [Completion certificate, Temporary permission to move in] }
      - { name: what_is_outstanding, type: textarea, optional: true }

  # --- the public: someone else is building ---------------------------
  - id: objection
    door: building-near-me
    who: a neighbour who got a notice about what is planned next door
    wants: what they think on the record, and answered in the decision
    requires: The notice that came in the post, which has the case number on it.
    lands_in: objections
    handled_by: case_officers
    stages: [open, registered, answered_by_applicant, addressed, withdrawn]
    done_when: [addressed, withdrawn]
    success: [addressed]
    # The firm that filed the case answers the objection; the neighbour
    # can take it back if they are satisfied.
    moves_by: { answered_by_applicant: [approved_firms, case_officers], withdrawn: [submitter] }
    watched_by: [public, section_head]
    mails: { open: submitter, answered_by_applicant: submitter, addressed: submitter }
    stages_text: { registered: on the case file, answered_by_applicant: the applicant has answered, addressed: answered in the decision }
    max_fields: 4
    collects:
      - { name: email, type: email }
      - { name: case_number }
      - { name: your_property }
      - { name: your_objection, type: textarea }

  - id: case-status-enquiry
    door: building-near-me
    who: someone waiting on a case and getting nothing back
    wants: to be told where it actually stands
    lands_in: enquiries
    handled_by: front_desk
    stages: [open, in_hand, answered]
    done_when: [answered]
    success: [answered]
    moves_by: { in_hand: [front_desk, case_officers] }
    watched_by: [case_officers]
    mails: { open: submitter, answered: submitter }
    max_fields: 3
    collects:
      - { name: email, type: email }
      - { name: case_number_or_address }
      - { name: what_you_want_to_know, type: textarea }

  - id: illegal-building-report
    door: building-near-me
    who: someone who can see building going up that nobody was told about
    wants: us to go and look, and to hear that we did
    lands_in: illegal_building
    handled_by: inspectors
    stages: [open, inspected, owner_asked, explained, resolved, fined, dropped]
    done_when: [resolved, fined, dropped]
    success: [resolved, dropped]
    # An inspector goes and looks; the letter to the owner is a case
    # officer's, and so is the fine.
    moves_by: { owner_asked: [case_officers], explained: [case_officers], fined: [section_head] }
    watched_by: [case_officers, section_head]
    turned_down_from: [open, inspected]
    mails: { open: submitter, inspected: submitter, resolved: submitter, dropped: submitter }
    stages_text: { owner_asked: the owner has been written to, explained: the owner has answered, dropped: nothing to pursue }
    max_fields: 3
    collects:
      - { name: email, type: email }
      - { name: address }
      - { name: what_you_saw, type: textarea }
      - { name: where, type: location, optional: true }

  # --- the public: after a decision ------------------------------------
  - id: appeal
    who: anyone with an interest who will not accept a decision of ours
    wants: the decision looked at again, by us and then by the board
    requires: A decision from us less than three weeks old, and its case number.
    lands_in: appeals
    handled_by: case_officers
    stages: [open, reconsidered, changed_by_us, before_the_board, upheld, overturned, withdrawn]
    done_when: [changed_by_us, upheld, overturned, withdrawn]
    success: [changed_by_us, upheld]
    # If we change our own mind that is the end of it, and it happens
    # while we are looking - not after the board has the case. The
    # board can only decide what has reached it.
    reached_from:
      changed_by_us: [reconsidered]
      upheld: [before_the_board]
      overturned: [before_the_board]
    # We look at ourselves first and the head of section decides whether
    # we were wrong. What we will not change goes to seven elected
    # people who meet once a month and move nothing else in this office.
    moves_by:
      changed_by_us: [section_head]
      before_the_board: [section_head]
      upheld: [appeals_board]
      overturned: [appeals_board]
      withdrawn: [submitter]
    watched_by: [public, front_desk, section_head]
    mails:
      open: submitter
      reconsidered: submitter
      changed_by_us: submitter
      before_the_board: submitter
      upheld: submitter
      overturned: submitter
    stages_text:
      reconsidered: we are looking at it again
      changed_by_us: we changed our own decision
      before_the_board: with the appeals board
      upheld: the board kept our decision
      overturned: the board overturned us
    max_fields: 5
    collects:
      - { name: email, type: email }
      - { name: case_number }
      - { name: property }
      - { name: what_you_disagree_with, type: textarea }
      - { name: your_interest, type: select, options: [I applied, I am a neighbour, Other] }

  # --- the public: a firm that wants to file here -----------------------
  - id: firm-approval
    who: an architect or engineering firm that files for its clients
    wants: to be on the list, and then to file without asking again
    lands_in: firms
    handled_by: case_officers
    stages: [open, papers_missing, checked, approved, declined]
    done_when: [approved, declined]
    success: [approved]
    skippable: [papers_missing]
    moves_by: { checked: [submitter, case_officers], approved: [section_head], declined: [section_head] }
    watched_by: [section_head, front_desk]
    turned_down_from: [open, papers_missing, checked]
    mails: { open: submitter, papers_missing: submitter, approved: submitter, declined: submitter }
    stages_text: { papers_missing: waiting on papers, checked: papers checked }
    max_fields: 6
    collects:
      - { name: firm_name }
      - { name: org_number }
      - { name: email, type: email }
      - { name: qualified_for, type: select, multiple: true, options: [Design, Execution, Independent control, Site management] }
      - { name: insurance_expires, type: date }
      - { name: insurance_document, optional: true }

  # --- approved firms ----------------------------------------------------
  - id: permit-application
    who: an approved firm filing on behalf of an owner
    wants: a decision inside twelve weeks, and to know when the clock stops
    enters_as: approved_firms
    lands_in: applications
    handled_by: case_officers
    stages: [open, incomplete, complete, on_hearing, recommended, approved, approved_with_conditions, refused, withdrawn]
    done_when: [approved, approved_with_conditions, refused, withdrawn]
    success: [approved, approved_with_conditions]
    skippable: [incomplete]
    # A case is sent back for the drawing it was missing, and the
    # hearing turns things up that send it back again. It may be
    # withdrawn from anywhere, and refused only once we have seen
    # everything: not on the day it arrives.
    reached_from:
      incomplete: [open, complete, on_hearing]
      refused: [complete, on_hearing, recommended]
    moves_by:
      complete: [submitter, case_officers]
      approved: [section_head]
      approved_with_conditions: [section_head]
      refused: [section_head]
      withdrawn: [submitter]
    watched_by: [public, front_desk, inspectors, section_head]
    mails:
      open: submitter
      incomplete: submitter
      on_hearing: submitter
      approved: submitter
      approved_with_conditions: submitter
      refused: submitter
    stages_text:
      incomplete: papers missing
      complete: papers complete
      on_hearing: out to the neighbours and the agencies
      recommended: recommendation written
      approved_with_conditions: approved on conditions
    max_fields: 6
    collects:
      - { name: email, type: email }
      - { name: property_address }
      - { name: property_number }
      - { name: what_is_planned, type: textarea }
      - { name: neighbours_notified, type: select, options: ["Yes", Not yet] }
      - { name: site, type: location, optional: true }
      - { name: drawings_url, optional: true }

  # --- the front desk -----------------------------------------------------
  - id: log-counter-enquiry
    who: whoever is on the counter with a queue and a caller on the line
    wants: the question written down and sent to whoever has the case
    enters_as: front_desk
    lands_in: enquiries
    handled_by: front_desk
    stages: [open, in_hand, answered]
    done_when: [answered]
    success: [answered]
    moves_by: { in_hand: [front_desk, case_officers] }
    watched_by: [case_officers]
    mails: { open: submitter, answered: submitter }
    max_fields: 3
    collects:
      - { name: email, type: email }
      - { name: case_number_or_address }
      - { name: what_you_want_to_know, type: textarea }

  # --- case officers ------------------------------------------------------
  - id: request-hearing
    who: a case officer sending a case out to the authority that must see it
    wants: an answer by the deadline, or a record that none came
    enters_as: case_officers
    lands_in: hearings
    handled_by: case_officers
    stages: [open, answered, no_answer, cancelled]
    done_when: [answered, no_answer, cancelled]
    success: [answered]
    # This is how an agency sees what it has been asked. Nobody presses
    # a button for the deadline passing.
    moves_by: { answered: [agencies] }
    watched_by: [agencies, section_head, front_desk]
    attended_by: >
      the six-week deadline: when it passes with nothing from the agency
      the case goes to no_answer and the application goes on without one
    stages_text: { no_answer: the deadline passed with no answer }
    max_fields: 4
    collects:
      - { name: case_number }
      - { name: which_authority, type: select, options: [Road authority, Fire service, Heritage office, The county] }
      - { name: what_we_ask, type: textarea }
      - { name: answer_by, type: date }
      - { name: site, type: location, optional: true }

  # --- the authorities outside the building --------------------------------
  - id: hearing-answer
    who: a road, fire, heritage or county officer who has been asked about a case
    wants: their answer on the file, in their own words
    requires: The hearing letter we sent you, which has the case number on it.
    enters_as: agencies
    lands_in: hearing_answers
    handled_by: case_officers
    stages: [open, read, followed, set_aside]
    done_when: [followed, set_aside]
    success: [followed]
    watched_by: [section_head, front_desk]
    stages_text: { read: read by the case officer, followed: followed in the decision, set_aside: set aside with reasons }
    max_fields: 4
    collects:
      - { name: case_number }
      - { name: which_authority, type: select, options: [Road authority, Fire service, Heritage office, The county] }
      - { name: our_answer, type: select, options: [No objection, Objection, Conditions required] }
      - { name: what_we_say, type: textarea }

  # --- inspectors -----------------------------------------------------------
  - id: inspection-finding
    who: an inspector on a scaffold with gloves on and the wind blowing
    wants: what they found logged before they climb down
    enters_as: inspectors
    lands_in: inspections
    handled_by: inspectors
    stages: [open, as_approved, deviation, put_right, escalated]
    done_when: [as_approved, put_right, escalated]
    success: [as_approved, put_right]
    # Anything that has to become a fine or a refusal leaves the
    # inspectors and becomes a case officer's problem.
    moves_by: { escalated: [case_officers, section_head] }
    watched_by: [case_officers, section_head]
    stages_text: { as_approved: built as approved, deviation: built differently, put_right: put right, escalated: handed to a case officer }
    max_fields: 3
    collects:
      - { name: case_number }
      - { name: site_address }
      - { name: what_i_found, type: textarea }
      - { name: where, type: location, optional: true }

# Held out from every model that writes words.
# arriving with one real thing, in their own register: a homeowner who
# has never read a regulation, a firm that files for a living, an
# inspector on a roof in the wind, a politician reading a bundle.
personas:
  - { id: garage-owner, need: pre-application-meeting, text: "We want to put a double garage where the old shed is. Before I pay an architect I'd like to know whether you'll even allow it, because the neighbour says it's too close to the road." }
  - { id: shop-to-flats, need: pre-application-meeting, text: "I own the old grocery on Torget and want to make four flats out of it. There are a lot of questions - parking, fire, the facade is listed. Can we sit down with someone?" }
  - { id: firm-files-extension, need: permit-application, text: "We are the responsible applicant for an extension at Bjorkeveien 14. Drawings, site plan and the neighbour notices are all ready. We file maybe forty of these a year." }
  - { id: owner-small-window, need: permit-application, text: "I want to put a dormer window in my roof. The man at the counter said I have to apply even though it's small." }
  - { id: missing-drawings, need: permit-application, text: "You wrote that our section drawing is missing and the case is on hold. I've got it here now, where do I send it so the clock starts again?" }
  - { id: too-close-to-boundary, need: exemption-request, text: "The garage ends up one and a half metres from the boundary and the plan says four. We are asking you to allow it anyway - the ground falls away steeply everywhere else on the plot." }
  - { id: neighbour-view, need: objection, text: "I got a notice about the extension at number 14. It takes the afternoon sun off my entire terrace and I want that on the record before you decide anything." }
  - { id: neighbour-parking, need: objection, text: "The flats they want to build in the old grocery have four parking places for four flats and everyone here already parks on the street. I object." }
  - { id: road-authority, need: hearing-answer, text: "Regarding your case 2026/418: the access onto the county road is within the sight line and we cannot accept it as drawn. Our formal reply is attached." }
  - { id: fire-service, need: hearing-answer, text: "We have looked at the conversion on Torget. We have no objection provided the stairwell is upgraded. Reference your case 2026/501." }
  - { id: refused-applicant, need: appeal, text: "You refused our exemption on the ninth. We don't accept the reasoning - you've allowed the same thing twice in the same street. We're appealing." }
  - { id: neighbour-appeals, need: appeal, text: "You approved the extension next door even though I objected. I'm appealing the decision. What do I need to send?" }
  - { id: board-member, need: appeal, text: "I sit on the appeals board. I need the case, our own decision, and what the neighbours wrote, before Tuesday." }
  - { id: inspector-on-roof, need: inspection-finding, text: "I'm up on the scaffold at Bjorkeveien. The fire wall isn't built to the drawing at all. I've got gloves on and it's blowing. I want this logged before I climb down." }
  - { id: inspector-all-good, need: inspection-finding, text: "Been out at Torget. Everything is as approved. Nothing to report but I have to record that I was there." }
  - { id: firm-wants-certificate, need: completion-request, text: "The work at Bjorkeveien 14 is finished and inspected. We're asking for the completion certificate so the owners can get their mortgage released." }
  - { id: wants-to-move-in, need: completion-request, text: "The house is done apart from the outside steps, which we can't pour until spring. The family has sold their flat. Can we get a temporary permission to move in?" }
  - { id: something-behind-fence, need: illegal-building-report, text: "There's a large structure going up behind the fence at Solbakken 7. Nobody has had a notice about it and it's been going on for two weeks." }
  - { id: owner-explains, need: illegal-building-report, text: "I got your letter about the terrace. I genuinely did not know it needed an application, it's been there since we moved in. What happens now?" }
  - { id: new-firm, need: firm-approval, text: "We are a three-person architecture firm that has just started. We want to be approved so we can file applications for our clients in your municipality." }
  - { id: firm-insurance-lapsed, need: firm-approval, text: "You wrote that our liability insurance certificate has expired. We have renewed it, here it is." }
  - { id: counter-phone-call, need: log-counter-enquiry, text: "A woman rang about the case behind her house. Wants to know where it stands. I'm at the counter and there's a queue - I need to write it down and send it to whoever has that case." }
  - { id: where-is-my-case, need: case-status-enquiry, text: "I sent in my application five weeks ago and I've heard nothing. Is anyone looking at it? Is it in the six weeks with the neighbours or is it waiting on me?" }