Coding policy — sharix-open-onboarding
- The onboarding project file is the only Stage 9 draft state. Do not introduce onboarding ORM tables as a convenience cache.
- Before Stage 9.3 materialization, real-mode views must not create or mutate business domain objects.
- Never store passwords, API tokens, private keys, acquiring credentials or uploaded identity/legal documents in
service-plan.json.
- Pre-install capability metadata is generic. Module-specific settings may only be exposed by an actually installed module contribution in Stage 9.2+.
- A closed/private unavailable module must not dead-end onboarding. Keep desired capability, chosen fallback/defer/custom implementation and limitation distinct.
- Do not invent a fallback that current core or an installed module cannot actually provide.
- Project writes must remain atomic, revision-safe and concurrency-safe.
- Demo mode reuses Stage 8 reference bootstrap; never create a second demo fixture system here.
- Stage closeout must record what/how/why/result plus verification and exact repository push commands.
Dialogue API boundary
- The versioned API edits only the established project design sections and
preserves execution, install evidence, immutable baseline and created_by.
- A plan UUID is not an access grant: every read/write requires the effective
onboarding role and the exact creator. Revision and design-hash confirmation
precede freeze and runtime actions.
- Read-only validation/preview must not create domain objects. Materialization
and existing-Service Apply delegate to the same canonical flows as the UI;
neither may approve a Ticket or infer live readiness from a started action.
- An uncertain runtime POST is reconciled by GET/preview, never blindly retried.
Stage 14 touched-page UI contract
This repository is a user-facing UI owner. Stage 14 uses progressive coverage rather than a one-time mechanical translation of every historical page. When a page, form, template or user-visible workflow in this repository is new or materially changed, the same change must close the local UI debt of that touched surface:
- localize the touched user-visible strings through the repository/module-owned Django i18n catalog and provide both
ru and en; do not move module strings into the root webapp catalog merely for convenience;
- keep canonical model/API/status/role/action codes unchanged and never branch business logic on translated labels;
- if the page participates in ShariX contextual help, update its help in the same change; help must explain the concrete operations available on that page, their prerequisites, result and important limitations, not only terminology or a general page purpose;
- review field labels, units,
help_text, choices, validation messages and empty states. Prefer an existing canonical finite choice/catalog over technical free text when that does not narrow the supported domain contract;
- invalid user input must remain a normal form/domain validation result, never an HTTP 500. In particular, a model/
ModelForm validation error keyed to a field must target a field that the form actually contains, or be deliberately converted to a non-field/form-owned error;
- an HTTP 200 page with a missing body is a regression, not an empty state. A legitimate empty dataset must explain why it is empty and, when the current role can act, what operation creates/configures the missing data;
- add/update regression evidence for the touched valid/invalid form path and rendered page body as appropriate.
Historical untouched UI may remain incomplete during the transition. A later change may not add another untranslated/unexplained fragment and defer the rest of the same touched page again.
Stage 15 compatibility and module metadata
The current project schema is version 4. Explicit v1 -> v2 -> v3 -> v4 migration remains supported. Stage 15.7.1 replaces the legacy Partner booleans with one semantic own_partner.partner_mode and replaces free-form custom-requirement ownership with target_type / target_ref / optional canonical definition_ref. Ambiguous legacy values must remain visible for explicit confirmation, and their original values remain compatibility evidence. A frozen legacy project whose approved hash belongs to the earlier semantic projection must be reviewed and frozen again before materialization; immutable old revision files are not rewritten.
Onboarding must consume canonical module metadata for capability purpose, implementing module, repository and actual license. sharix_translations is GPL v3/public; sharix_russian_post is private/proprietary. Do not infer license from availability (public/free, closed/private) and do not create a second module-status catalogue inside onboarding.
Stage 16.11 existing-Service invariants
- Keep the historical technical
mode=real contract unchanged. onboarding_mode carries the new new / existing distinction.
- An existing-Service project owns an immutable actor-scoped runtime baseline plus mutable apply-state evidence; apply-state is not part of the frozen design hash.
- Never infer edit authority from Provider/Partner/ordinary User participation. Existing-Service onboarding remains under the
METASERVICE-ADMIN boundary and revalidates that boundary at apply time.
- Existing objects use stable
source_ref identities. A supported edit updates the referenced object through canonical forms/lifecycle; it must not create a duplicate object.
- Re-read and lock mutable targets immediately before apply. Baseline/runtime/desired conflicts block overwrite and require explicit review/rebase.
- New-object creation and deletion are not silently synthesized by the existing-Service editor; use the standard domain creation/deletion lifecycle until a dedicated onboarding mapping is implemented.
- Approval-capable requesters are never auto-approved by onboarding. Normal lifecycle Tickets remain normal Tickets; onboarding may only surface their IDs/review links.
- Runtime snapshots contain no secrets and may include read-only requirements, checks, relationships, Providers and Orders needed for impact context. Read-only contextual drift does not become an editable three-way conflict.
Stage 15.7.1 semantic migration invariants
- Do not reintroduce
enabled / same_as_operator as ordinary Partner UI controls.
- Runtime requirement ownership must never be recovered by parsing localized free text.
- Reusing a
CheckDefinition or DocumentTypeDefinition requires revalidation at form submit and again immediately before materialization.
needs_confirmation is a migration state only; freeze is blocked until the user selects a real semantic owner/mode.
- Old frozen plans whose design hash changes under the v3 semantic representation require an explicit review/refreeze path rather than silent acceptance or destructive rewriting.