Development lifecycle | Arcane OS Docs

Current operating profile

ARCANE is currently a development-only project.

There is no staging environment.
There is no production environment.
There are no staging or production branch protections.
main, feature branches, and work branches are development branches.
No build, package, workflow result, screenshot, demonstration, or checked-in dist/ tree is a release candidate or production claim.

This profile is intentionally optimized for rapid implementation, experimentation, and internal demonstrations. It does not waive the development safety invariants below.

Arcane OS as an SDK-consuming application

Arcane OS is the orchestrator, launcher, shell, and system artificial- intelligence application layer built on the Arcane SDK. It follows the same source-development, explicit SDK-consumption, packaging, capability, and distribution paths as an ordinary portable application. Development resolves portable mechanisms through the explicit Arcane SDK source path; distribution uses the selected materialized SDK runtime. Any retained arcane/** tree is a generated SDK projection and is never independently edited.

Reusable portable modules, entities, components, browser runtimes and providers, protocol/state/lifecycle machinery, themes, assets, and public native-capability contracts or adapters belong canonically in the SDK. Arcane OS owns only launcher/session/shell composition, privileged native/Core host implementations, and shell-specific system-AI policy. Product branding, prompts, data, tools, business policy, model authorities, and orchestration stay with the owning application. Applications declare and select native capabilities and return an honest unsupported result when the required host is absent without disabling unrelated ordinary behavior.

Use the decision order and placement rules in app-building.md: reusable portable behavior goes to the SDK; host privilege or launcher/shell responsibility goes to Arcane OS; one-product behavior goes to that application. Never create copied app-local or OS-local implementations to share behavior.

Default development loop

Ordinary development does not select a test or check automatically. Use the smallest authorized path:

make the focused change;
inspect the intended source and diff without executing tests or checks;
run a focused test or npm run check only when the user explicitly requests it;
package only the selected application when an actual package or demonstration is needed;
run an application's full suite only for that application's release;
use the Arcane OS integration, native-host, or release command only for an explicit Arcane OS release moment or when the work affects that boundary.

The current command profiles are:

Profile	Command	Purpose
Rapid development invariants	`npm run check:dev`	Explicitly selected checkout, dependency-source, setup, version, path, catalog, badge, and release-profile diagnostics.
Development handoff	`npm run check`	Explicitly selected development check profile.
Application demo	`npm run demo:check -- <app-id>`	Rebuild and verify only the selected browser-context application package.
Application release	App-owned release command	Releases only the selected application; its tests run only when separately authorized or required by that selected output.
Arcane OS integration	`npm run check:integration`	Explicit portable Arcane OS integration profile; excludes application behavior suites.
Microsoft NT iteration	`npm run check:windows:fast`	Explicit fast native-host iteration build; not release evidence.
Arcane OS release	`npm run release:check:arcane-os`	Explicit Arcane-OS-only selected release output; it does not run app-owned behavior suites.

npm test, npm run check:dev, and npm run check are opt-in. Ordinary iteration, setup, commit, push, handoff, and completion do not authorize them. Hooks and continuous-integration workflows must not invoke tests or checks automatically unless the user has selected that exact verification; current tooling compliance is unverified until the tooling owner completes the source reconciliation. npm run release:check remains a compatibility alias for an explicitly selected Arcane OS release output; it does not select signing.

The complete Arcane OS suite runs only for an explicit Arcane OS release. An application release does not select that suite, and an Arcane OS release does not select any application's complete suite. These are separate release decisions owned by separate products.

Mandatory work-amplification review

Before implementing or materially changing setup, build, package, test, model, app, or runtime work, complete the work-amplification review in app-building.md and build-release.md. State the cardinality and loop multiplier, classify expensive operations as invariant, reusable, batchable, or necessarily per item, and estimate a representative cold-path operation count, allocation behavior, and elapsed time. Hoist invariant work, reuse results only while their real semantic inputs and invalidation rules remain valid, batch compatible work, and document every justified repetition.

Setup and OS builds must not compile apps or repeat OS-owned downloads, extraction, authorized dependency installation, compilation, model service setup, or runtime preparation once per app. Optional hashing, signing, integrity, provenance, trust, and security work remains inactive without exact authorization. Apps own independently selected output; Arcane OS consumes it through the functional package contract.

Measure a representative cold path after implementation. Eliminate redundant work before adding progress UI, then preserve phase, current item, completed/total item count, elapsed time, heartbeat, and an honest ETA when available. A faster-looking progress bar does not make repeated work acceptable.

The responsiveness invariant applies in every lifecycle profile. A UI or CLI acknowledges immediately before potentially blocking work; network, disk, compilation, process, and model work never delays UI creation or blocks its foreground thread. Use event-driven background workers or genuine asynchronous I/O. async/await must not wrap synchronous blocking work. Bound concurrency and apply backpressure; emit progress and heartbeat events; support cancellation and safe retry/resume where practical; and give every task an owner that surfaces failures. Unobserved fire-and-forget work is prohibited. Serialize only the narrow shared-state or unavoidable external-protocol boundary that actually requires ordering.

The approved OS test taxonomy, no-residue contract, and migration inventory are documented in os-testing.md and os-test-inventory.md. The managed unit, functional, UI-integration, portable-system, smoke, and combined c8 profiles are active and report numeric set results. Native-system profiles remain explicitly marked not run until their target-specific migrations produce current evidence.

Development data and platform boundaries

Development work must:

keep credentials, secrets, private keys, protected operational data, and production identities out of source, fixtures, logs, commits, and demos;
use synthetic or disposable data;
preserve explicit privacy choices and non-optional law or platform safety;
keep destructive experiments bounded to disposable data or a disposable machine with exact ownership; and
label development output accurately.

These narrow requirements do not authorize optional security, hardening, provenance, integrity, isolation, signing, trust, or restrictive admission. Those controls require the user's express authorization for the exact scope.

Internal demonstration boundary

An internal demonstration may use:

source-hosted applications;
the selected app's dist/<app-id> package;
an explicitly labeled development native build;
synthetic content and development-only providers;
a developer workstation or disposable test machine.

An internal demonstration must not:

be described as staging, production, release-candidate, certified, approved, hardened, or ready for deployment;
use production credentials, protected operational data, or real participant records;
claim that unperformed release, security, privacy, accessibility, update, recovery, or rollback work passed.

If a demonstration needs real protected data, real users, production credentials, unattended elevated operations, or deployment outside the controlled development group, it has crossed the development boundary and needs an explicit promotion decision.

Generated packages during development

Checked-in generated packages are not required to be refreshed for every source edit during rapid development. Generate only the package needed for the current demonstration or package-specific investigation.

Review generated output before intentionally committing it.
Do not hand-edit generated manifests.
A stale development dist/ tree is not evidence that its source is broken or release-ready.
A demo handoff must identify the exact generated directory and the command used to build it.
Full regeneration of affected public packages is deferred to an explicit integration or promotion change.

Application behavior and publication belong to the application that owns them. The application payload an Arcane OS build consumes is the selected dist/<app-id> release rooted in ARCANE_APP_RELEASE.json. The OS consumes its identity, declared capabilities, entry point, and complete inventory through the functional package contract. It may reject a genuinely malformed package, but must not introduce byte, hash, provenance, trust, or restrictive admission gates without exact authorization.

The OS must not use apps/<app-id> source as its payload, import or execute an app adapter, generator, or source verifier, rebuild an app, or run an app's content or business-behavior suite. A missing or malformed ARCANE_APP_RELEASE.json is reported through the package owner and is repaired through the app's own release process; it never causes the OS to take ownership of app verification. Each application advances its independent version only when that application is explicitly released. Its suite runs only when separately authorized or required by that selected release output.

This policy keeps high-fan-out generated files out of ordinary feature decisions while retaining deterministic package tools for the point at which an artifact is actually needed.

Keep the current tree current

Git is Arcane's version history. The working tree contains the current canonical source, documentation, contracts, and intentionally published artifacts—not duplicate historical copies.

Update the canonical file or directory in place and remove its superseded copy in the same change.
Do not retain old version-numbered source directories, prior validation records, renamed backups, superseded generated artifacts, or obsolete release archives merely as history or evidence; Git already preserves them.
Record a concise compatibility or migration note in the changelog when current users need it instead of keeping the replaced implementation beside the new one.
Keep historical material in the current tree only when a current runtime, legal obligation, or explicitly selected audit scope requires it. Document its current purpose and dependency beside the retained material and keep the scope minimal.
Review generated and binary artifacts for continued current use. Remove them when the supported generator, dependency snapshot, or release no longer consumes them.
Before deleting tracked material that setup or a package manager can rewrite, prove a normal pull from every supported previously set-up checkout. If a dormant checkout could skip an intermediate migration and conflict with a later deletion, retain only the smallest documented compatibility shim; a version increment by itself is not proof that users absorbed an intermediate commit. Optional Git-metadata cleanup must never change object IDs or staged content and must never block pull, setup, validation, or build. Never make ordinary users stash, reset, or resolve generated-file conflicts to receive routine cleanup.

This rule applies equally to code, docs, machine bundles, applications, examples, evidence, and generated output. “For reference” by itself is not a reason to keep a superseded copy.

Run repository cleanup only as a separately selected operation, such as before an explicit release or when obsolete generated/cache content accumulates:

run npm run cleanup:preview to list ignored files Git would consider removable;
review the list and remove only exact generated/cache paths that are no longer needed—never use a broad cleanup command against unreviewed user data, credentials, evidence, or hydrated development dependencies;
remove superseded tracked material only after inspecting current consumers; run prior-checkout migration verification only when separately authorized;
run npm run maintenance:gc for safe local Git object maintenance;
inspect git status and the intended diff; run current-tree invariants or a selected release profile only when that verification is separately authorized or required by the selected output.

maintenance:gc uses git gc --auto. It does not rewrite shared history, delete remote refs, or purge Git LFS storage. History rewrites, aggressive pruning, and remote LFS deletion are separate destructive maintenance operations requiring explicit authorization, recoverable copies, and remote-owner coordination.

Accessibility deltas and optional controls

During development, record only the decision that materially affects the design:

Accessibility delta: Does this change introduce a new interaction model, block keyboard operation, remove semantic information, depend on one sense, or change a protected confirmation/recovery path?

Preserve the accessibility contract in source. Add or run focused checks only when the user explicitly requests them or when a selected output requires that verification. Security, privacy, hardening, signing, provenance, trust, or admission review is not inferred from this section and requires exact user authorization.

Escalation boundary

Stop and request the exact expanded authority before:

calling any artifact a release candidate, staging build, pilot build, or production build;
using production signing material or asserting publisher continuity;
deploying to real participants or operational users;
processing protected or operational data outside a deliberately synthetic test;
introducing or materially changing an actual privilege, identity, authorization, or cross-user boundary; or
asking an independent authority to accept security, privacy, accessibility, or operational risk.

Future promotion plan

Future promotion is inactive until the user explicitly selects the exact output and scope. Existing release, security/privacy, accessibility, traceability, signing, rollback, or pilot documents do not activate those controls.

When the user explicitly selects promotion:

define the supported product and deployment claim;
choose the selected output and environment;
run only the verification required by that selected output;
obtain separate application evidence only for applications included in the selected product claim; and
add signing, security/privacy, accessibility, traceability, rollback, or operational work only when each exact scope is expressly authorized.

Suggested future branch roles, which are intentionally not configured yet:

Future branch	Intended role
`main`	Integrated development baseline until a staging branch exists.
`stage`	Protected candidate-integration branch with full portable/native gates and a non-production environment.
`release/*`	Possible future release-candidate branch after explicit selection.
production tag	Possible future selected product version.

Adding those branches alone must not activate deployment. Their workflows, credentials, environments, protections, and authority rules must be reviewed and enabled together.

Repository and reviewed source access