Skip to content

Last reviewed: 2026-08-13 Accepted decision: - ../decisions/accepted/0035-controlled-conversion-setup-review-pause.md

Setup Readiness Contract

Canonical objects:

  • SetupReadinessItemDefinition
  • SetupReadinessReport
  • SetupReadinessItemResult
  • SetupReviewSubject
  • SetupAcknowledgement

Purpose

Setup readiness gives one company-scoped, ordered explanation of whether a startup company can proceed from onboarding into current-period work. It composes facts owned by Company, Financial Periods, Accounts and Account Roles, Security, and Accounting. It does not replace those owners or create a second source of accounting, authorization, or audit truth.

Stable readiness registry

Every readiness item has a stable id, display order, completion mode, governing owner, prerequisites, allowed acknowledgement outcomes, and review-subject definition when human review is required. Unregistered item ids and outcomes must be rejected.

The initial-release order and meaning are:

Order Item id Completion and governing owner
1 company_identity Objective Company fact: the same-company identity exists, is not retired, and has its required launch fields. No acknowledgement is allowed.
2 responsibilities_reviewed Current reviewed acknowledgement of the responsibilities subject defined below.
3 policy_baseline_reviewed Current reviewed acknowledgement of the policy-baseline subject defined below.
4 reporting_currency_reviewed Current reviewed acknowledgement of the company's displayed base/reporting currency and the initial-release single-currency boundary.
5 fiscal_calendar_active Objective Financial Period fact: one same-company fiscal-calendar profile is active. No acknowledgement is allowed.
6 first_period_open Objective Financial Period fact: at least one same-company fiscal month is open or reopened. No acknowledgement is allowed.
7 chart_ready Composite Accounts fact plus current reviewed acknowledgement: an active same-company chart exists, no starter-chart collision review is pending, and the exact selected chart result was reviewed.
8 account_roles_reviewed Composite Account Role fact plus current reviewed acknowledgement: every required launch role resolves once to an eligible same-company account and the exact assignments were reviewed.
9 permissions_ready Current reviewed acknowledgement of the permission-review subject defined below. Bootstrap authority alone never completes this item.
10 opening_balances_ready Accounting fact or explicit disposition: a supported same-company opening-balance entry was posted through central Accounting, or a current not_required acknowledgement records why opening balances are not required.

The registry order is the onboarding order. A presentation may group related items, but it must not silently reorder the next incomplete or blocked item.

Allowed acknowledgement outcomes are stable contract values:

  • reviewed; and
  • not_required.

not_required is allowed only for opening_balances_ready. Objective items do not accept acknowledgements.

Readiness result

Every item result must expose:

  • item id and display name;
  • status;
  • business-language detail;
  • the current objective or reviewed subject;
  • the latest acknowledgement when one exists;
  • whether that acknowledgement is current;
  • a stale reason when it is not current;
  • blockers; and
  • the next action available to the user.

Stable status values are:

  • not_started: required objective facts or current review evidence are absent;
  • blocked: a prerequisite, conflict, retired company, or invalid governing fact prevents valid completion; and
  • complete: every objective condition and current acknowledgement required by that item is satisfied.

A stale acknowledgement does not create a fourth status. The item evaluates to not_started when a new review can proceed, or blocked when an unresolved governing conflict or prerequisite prevents review.

An acknowledgement cannot override a blocker, supply an objective fact, grant a permission, open a period, install or alter a chart, assign an account role, or post an opening balance.

Review subjects

A review acknowledgement is valid only for the exact subject the user could inspect before acknowledging it. A SetupReviewSubject must include:

  • company id;
  • item id;
  • subject type and durable subject reference;
  • a deterministic subject version or fingerprint;
  • the business-facing fields presented for review;
  • the time the subject was assembled; and
  • references to governing records or evidence needed for later explanation.

The displayed subject must use recognizable company, actor, account, period, role, protected-action, and evidence references. Raw ids may accompany those references for audit or troubleshooting, but must not be the only ordinary review content.

Responsibilities review must show, at minimum:

  • the responsible person or explicit unassigned state for routine accounting preparation and posting;
  • accounting review and correction oversight;
  • period-close and financial-report review;
  • production security administration; and
  • backup and recovery stewardship.

One person may hold several responsibilities. The subject must make that fact visible; it does not manufacture separation of duties or grant application permissions. An unassigned required responsibility prevents a current reviewed outcome.

Policy-baseline review must show one business-approved, versioned baseline or evidence reference covering, at minimum:

  • accounting basis and recognition approach;
  • materiality and supporting-evidence expectations;
  • revenue, expense, cash, receivable, payable, inventory when applicable, tax, debt, and owner-transaction treatment at the policy level;
  • manual journal, adjustment, and correction expectations; and
  • period-close and financial-review expectations.

The policy baseline documents decisions; it does not activate deferred workflows, override canonical posting or Close rules, or imply that BooksPlus automatically enforces every documented policy.

For the initial release, BooksPlus records these two subjects by external reference rather than becoming the system of record for responsibility or accounting-policy documents. The responsibilities subject records a versioned external evidence reference plus the displayed responsible person or explicit unassigned state for each required responsibility. The policy-baseline subject records a versioned external evidence reference and displays the required coverage areas above. BooksPlus preserves the reviewed reference, version, displayed fields, and fingerprint; it does not author, approve, or interpret the referenced business documents. Changing the reference, version, or any displayed responsibility assignment creates a new subject and makes an older acknowledgement stale.

Reporting-currency review must show the company display name, selected base/reporting currency, and that the initial release permits ledger posting and formal statements only in that currency.

Chart review must show the acquisition path—starter installation, reviewed existing chart, or supported staged import—and the resulting accounts needed for review, including code, name, type, status, posting eligibility, source, and starter identity when applicable. Pending collisions and unresolved import issues remain visible blockers.

Account-role review must show every required launch role, its cardinality, assigned account code and name, immutable account reference, and eligibility. Missing, duplicate singleton, inactive, retired, non-posting, wrong-company, or otherwise ineligible assignments remain blocked.

Permission review must show:

  • same-company actor-role assignments;
  • each role and its protected-action permissions;
  • each registered protected action and its covering roles and assigned actors;
  • reason and step-up flags where defined; and
  • clear development/test-only and bootstrap-role labels.

Permission review records what was inspected. It does not define final production role templates, create assignments, authorize an action, or make a development/test role valid in production.

An opening-balances not_required subject must identify the company and setup scenario, state the reviewed reason, and reference supporting evidence when applicable. It is not a zero-balance journal entry and does not authorize a later hidden balance edit.

Setup acknowledgements

Setup acknowledgements are append-oriented company-owned evidence. A current acknowledgement must preserve:

  • id, company id, and readiness item id;
  • outcome;
  • acknowledging actor and time;
  • explanation;
  • subject type, durable subject reference, and subject version or fingerprint;
  • evidence reference when applicable; and
  • correlation id when part of a larger setup action.

The latest valid acknowledgement for an item supersedes older acknowledgement evidence for currentness; older records remain preserved. Retired companies cannot receive new setup acknowledgements.

Acknowledgement is distinct from security audit evidence. A protected action used to assemble or change the reviewed subject follows its governing security and audit rules. Recording a setup acknowledgement does not by itself prove authorization for those subject changes.

Currentness and invalidation

Readiness must be recomputed from governing facts and the exact reviewed subject. It must not be retained merely because an item was previously marked complete.

An acknowledgement is stale when its subject fingerprint no longer matches the current subject or when a later governing event changes material reviewed meaning. At minimum:

  • a legal/display name, accounting time zone, status, or other required company-field change updates company_identity immediately; a base-currency or displayed company-reference change invalidates reporting_currency_reviewed;
  • a responsibilities assignment or referenced responsibilities-document version change invalidates responsibilities_reviewed;
  • a policy-baseline version, content fingerprint, or evidence-reference change invalidates policy_baseline_reviewed;
  • fiscal-profile retirement or replacement and the absence of an open or reopened fiscal month update their objective items immediately;
  • a pending starter-chart collision, changed chart/import result, collision resolution, or material account review-field change invalidates chart_ready and any older dependent account-role review;
  • a required-role assignment or assigned-account eligibility change invalidates account_roles_reviewed;
  • an actor status, company assignment, role, role permission, protected-action registry, reason flag, step-up flag, development/test designation, or bootstrap-role change invalidates permissions_ready; and
  • posting an opening-balance entry conflicts with a prior not_required disposition and requires explicit review rather than silent coexistence.

An invalidation does not delete, edit, or backdate prior evidence. The item shows the prior acknowledgement as stale, explains the changed subject, and offers the governed recovery action.

A replacement conversion follows the same invalidation rule. After its chart step is durably applied, the conversion remains applying and pauses before opening-balance posting until the user reviews the exact resulting chart and then the valid required-role assignments through ordinary Setup. Conversion approval is not Setup review evidence.

Prerequisites and completion

A prerequisite controls whether an action can validly proceed; it is not merely visual ordering. At minimum:

  • company identity is required for every later company-scoped item;
  • an active fiscal calendar is required before the first posting period can be open;
  • unresolved chart acquisition or collision work blocks chart and account-role completion;
  • chart readiness is required before account-role review;
  • fiscal calendar, first open/reopened month, chart, account-role, and permission readiness are required before opening-balance posting; and
  • every registry item must be complete before Setup reports overall completion.

The first non-complete item in registry order is the suggested next action. When that item is blocked, the next action must identify the prerequisite or conflict and its recovery path rather than skipping ahead or accepting an acknowledgement.

Overall completion is an evaluated state, not a one-time mutable flag. It does not grant permissions, post another entry, close a period, start conversion, or prevent later configuration changes.

Later re-entry and history

Setup remains available after completion. Re-entry must show current governing facts, the evidence that supported prior completion, and any later staleness or blocker. A company may continue current-period work only as allowed by the governing Accounting, Financial Period, and Security rules; the setup summary does not bypass those controls.

Readiness items, review subjects, acknowledgements, and their company ownership must survive application restart, company backup, and restore according to the Company Backup Snapshot Contract. Restore-time security-assignment review remains governed by that contract and can make permission readiness stale.

Boundaries

This contract does not define:

  • final production role templates or the final role-permission matrix;
  • full production user administration or administrator recovery;
  • support-access grant, use, or revoke workflows;
  • QBO conversion or another replacement-source transport;
  • implementation-services practice management;
  • new accounting policies, posting rules, Close rules, or automated closing entries; or
  • permission for a presentation layer to mutate governing domain records.

Acceptance criteria

  • Every initial-release readiness item has one stable id, owner, completion mode, subject boundary, prerequisite rule, and invalidation rule.
  • Objective items cannot be completed by acknowledgement.
  • Acknowledged items cannot be complete without an inspectable current subject and matching acknowledgement fingerprint.
  • Responsibilities and policy acknowledgements cannot be recorded from a generic button without displaying their governed subject.
  • Blocked items explain the conflict and recovery action and cannot be skipped by acknowledgement.
  • A material subject change makes prior evidence visibly stale without deleting it.
  • Overall completion requires every registry item to be complete and is recomputed on later Setup entry.
  • Company switching and restore cannot carry another company's readiness, subject, acknowledgement, authorization, or evidence state into the active company.