Governance Forms Autofill State Discovery

Document ID: GOS-40-FORMS-AUTOFILL-STATE-DISCOVERY
Version: 1.1.0
Status: DRAFT
Owner Role: DOCUMENT_CUSTODIAN
Last Review Date: 2026-02-26
Next Review Date: 2026-03-28

1. Purpose

This note captures which workflow states are required to support automatic form filling in a deterministic way.

Goal:

• define minimum state gates for autofill
• identify gaps between governance state-machine documents and current runtime states
• provide an implementation-ready baseline for form automation

2. Current State Coverage

2.1 Land Owner / Plot Registration

Governance spec (EX-PL-01) states:

• DRAFT
• SUBMITTED
• UNDER_VERIFICATION
• VERIFICATION_COMPLETED
• CORRECTION_REQUIRED
• REGISTERED
• DECLINED
• CANCELLED

Current runtime onboarding states (stakeholder application):

• DRAFT
• SUBMITTED
• UNDER_REVIEW
• REQUIRES_INFO
• APPROVED
• VERIFIED
• REJECTED
• EXPIRED
• SUSPENDED

Current UI edit gate:

• editable only in DRAFT or REQUIRES_INFO
• submit allowed only when editable + required docs + at least one plot

Gap:

• EX-PL-01 states are not directly implemented as runtime values.
• onboarding currently runs on stakeholder_application state machine, not on EX-PL-01 canonical labels.

2.2 Tender (EX-TN-01) and Procurement (EX-PR-01)

Governance spec states are richer than runtime tender status.

EX-TN-01 includes:

• DRAFT, PUBLISHED, BIDDING_OPEN, BIDDING_CLOSED, UNDER_EVALUATION, SELECTION_PROPOSED, APPROVED, REJECTED, CLOSED

EX-PR-01 includes:

• INITIATED, ELIGIBILITY_REVIEW, TENDER_OPEN, TENDER_CLOSED, EVALUATION, SELECTION, DECISION, CORRECTION, REJECTED, SETTLED, CLOSED

Current runtime tender status:

• DRAFT
• SUBMITTED
• APPROVED
• REJECTED
• CANCELLED

Gap:

• procurement/tender governance phases are not fully represented in runtime tender status.

2.3 Contract (EX-CT-01) and Settlement (EX-ST-01)

EX-CT-01 states:

• PROPOSED, LEGAL_REVIEW, APPROVED, SIGNATURE_AUTHORIZED, SIGNED, CLOSED, CANCELLED

EX-ST-01 states:

• INITIATED, PAYMENT_EVIDENCE_SUBMITTED, UNDER_VERIFICATION, VERIFIED, ANCHORED, SETTLED, REJECTED, CANCELLED

Runtime:

• auction/tender services expose partial lifecycle states.
• settlement-specific workflow states are mostly specification-level today.

2.4 EX-IP-04 Inspection

Current governance state machine (EX-IP-04) states:

• INITIATED
• SUBMITTED
• ASSIGNED
• UNDER_INSPECTION
• UNDER_VERIFICATION
• VERIFICATION_COMPLETED
• UNDER_REVIEW
• DECISION_PENDING
• CORRECTION_REQUIRED
• APPROVED
• REJECTED
• ANCHORED
• SETTLED
• CLOSED
• CANCELLED

Impact:

• inspection form automation can now use canonical lifecycle gates instead of placeholder assumptions.

3. Required Autofill State Gates

To safely automate form filling, each form instance needs these lifecycle gates:

1. NOT_STARTED

• No instance yet.
• Allow only identity/profile prefill.

2. DRAFT_EDITABLE

• Owner fields can auto-populate from known sources.
• User can override allowed fields.

3. READY_TO_SUBMIT

• Derived validation state (required records present).
• No transition yet, only gate check.

4. SUBMITTED_LOCKED

• Content is immutable for owner.
• Only review metadata can be appended.

5. UNDER_REVIEW_LOCKED

• Reviewer-only actions.
• Owner edits blocked.

6. REQUIRES_INFO_EDITABLE

• Targeted correction mode.
• Autofill should preserve prior values and apply only requested deltas.

7. APPROVED_OR_VERIFIED_LOCKED

• Decision complete.
• No editable payload fields.

8. ANCHORED_OR_SETTLED_OR_CLOSED_TERMINAL

• Finalized record context.
• Read-only; evidence and proof only.

9. REJECTED_OR_DECLINED_OR_CANCELLED_TERMINAL

• Terminal negative path.
• Read-only with reason/evidence visibility rules.

10. EXPIRED_OR_SUSPENDED_LOCKED

• Administrative lifecycle lock.
• Read-only unless explicit governance policy allows reactivation.

4. Minimum Data Sources for Autofill

Autofill engine should read from canonical aggregates:

• application state: stakeholder_applications.state
• profile patch aggregate: stakeholder_application_payloads.payload_json
• plot records: land_plots
• document records: stakeholder_application_documents
• audit timeline: stakeholder_application_events (for timeline/audit, not as sole truth source)

5. Implementation Order

1. Publish a canonical crosswalk:

• map governance states to runtime states per domain (EX-PL/EX-TN/EX-PR/EX-CT/EX-ST).

2. Map EX-IP-04 states to lifecycle gates in code:

• ensure correction and decision loops are represented in form mutability rules.

3. Introduce a shared form lifecycle enum in code:

• use the gates listed in Section 3.

4. Enforce state-aware field mutability:

• editable fields only in editable gates.
• computed/autofilled fields read-only in locked/terminal gates.

5. Add projection endpoint(s):

• return current gate + missing requirements + prefilled payload in one response.

6. Open Governance Decisions

• Final authority mapping for some EX-PL transitions is still UNDEFINED.
• Correction loop bounds are UNDEFINED in multiple procedures.
• EX-IP-04 reviewer mandatory/optional policy is still UNDEFINED.
• Public visibility and disclosure policy details remain procedure-specific UNDEFINED items.