Testing Arcane OS | Arcane OS Docs

Current phase: This document defines the active OS testing model. The audited inventory and migration record are in os-test-inventory.md. Catalog-driven unit, functional, UI-integration, portable-system, and smoke profiles are active; native and acceptance evidence remains explicit and target-specific.

Purpose and scope

This SOP makes every ARCANE OS test answer a specific engineering question at the cheapest trustworthy boundary. It applies to the machine bundle, Core, Shell, Provisioner, native hosts, shared runtime mechanisms embedded by the OS, OS build and packaging tools, and OS development-policy gates.

Application teams may reuse this taxonomy, metadata, duplication rules, and cadence. Application business logic and application-specific journeys are not part of the current OS migration.

This SOP follows the development-only lifecycle in development-lifecycle.md: use the smallest check that answers the current question, retain the development safety invariants, and reserve full native and acceptance evidence for affected boundaries or an explicit promotion decision.

Test model at a glance

ARCANE OS separates test layers so each engineering question is answered once at the cheapest trustworthy boundary. Passing a lower layer never stands in for evidence that only a real package, native host, or acceptance journey can provide.

Layer or profile	What it proves	Current role
Static conformance	Source, configuration, generated output, or package structure has the required shape.	Active prerequisite checks; never reported as runtime behavior.
Unit	One deterministic exported mechanism behaves correctly in isolation.	Active portable suite and the fastest focused behavior check.
Functional	One public OS capability works through its real JavaScript boundary.	Active portable suite for capability changes and integration.
Controller UI integration	Real Shell or Provisioner markup and controllers complete a user journey.	Active shared-DOM profile; native rendering claims still require a real engine.
Portable system integration	Built Core, RPC, package, or integrity pieces compose across a process or artifact boundary.	Active integration profile for cross-boundary changes.
Smoke	A deliberately small selection of canonical cases checks artifact health.	Active four-case profile; cases are selected, never copied.
Native platform integration	A compiled Microsoft NT, Linux, or Android host and distribution work on that target.	Explicit target-specific evidence; portable or simulated checks cannot substitute for it.
Acceptance	An exact candidate completes a real-host, human-meaningful journey.	Promotion-only evidence, outside routine development automation.
JavaScript coverage	The unit and functional union executes the owned JavaScript to the documented threshold.	One explicit `c8` workflow, separate from smoke and ordinary development checks.
Application-owned suites	Application business logic, content, and journeys behave correctly.	Owned by each application and kept separate from the OS gate.

The sections below define each layer, its evidence limits, when it runs, and how the named commands compose without executing a selected case twice. The companion test inventory records the canonical owners and current migration state.

Governing rules

Every test has one documented requirement or invariant, one risk-based reason to exist, and one canonical owner.
A test is classified by the boundary it actually executes, not by its filename, historical command, or use of the word smoke.
Lower layers prove logic. Higher layers prove composition or the behavior of an exact artifact. A higher layer must not repeat lower-layer assertions that do not cross its additional boundary.
Source-text assertions prove structure only. They must not be presented as runtime, native-platform, accessibility, security, or acceptance evidence.
Tests use synthetic or disposable data. Routine automated tests never mutate real accounts, approve elevation, overwrite installed services, use production credentials, or claim release readiness.
Security, privacy, accessibility, regression, platform, and performance are tags or evidence dimensions, not substitutes for a test type.
Coverage is evidence about executed JavaScript, not a test type or a proxy for correct requirements.
A smoke check is a deliberately small profile assembled from applicable test types. smoke is not a bucket for every test that does not otherwise have a name.
A test that leaves unexplained files, directories, processes, sockets, services, users, registry values, environment changes, caches, or generated output is failing even when its behavior assertions pass.
A test whose reason cannot name a material defect, contract violation, or user-visible risk is not retained merely because it already exists or adds coverage.

Clean-test contract

Routine automated OS tests must leave the workstation and checkout in the same material state in which they found them.

Create every disposable resource under a unique per-run temporary root from the operating system's temporary-directory API. Resolve and verify that root before using any recursive cleanup operation.
Register cleanup immediately after creating a resource and execute it from a finally block. Cleanup must run after success, assertion failure, timeout, cancellation, and expected child-process rejection.
Run resource-creating test workers under a parent supervisor that owns their temporary root, process tree, ports, pipes, sockets, and cleanup deadline. After a worker crash or timeout, the supervisor must terminate and reap the complete process tree, perform cleanup, and verify absence independently of code inside the failed worker.
Track every child process, server, named pipe, Unix socket, file handle, watcher, timer, and temporary environment override. Close or terminate it deterministically and await completion before the test exits.
Outside the operating system's designated temporary subtree, never write routine test data to a user profile, home directory, desktop, documents folder, application-data folder, installed ARCANE directory, Program Files, ProgramData, /opt, /usr, service manager, registry, login shell, real model store, shared npm cache, or another repository checkout.
Do not write generated build output into a canonical dist/, runtime/, or source directory merely to test a pure mechanism. Use a disposable output root or compare an in-memory rendering. An integration test may use the canonical build output only when that exact artifact is its declared subject.
Do not reuse a fixed temporary path, port, pipe, socket, account name, service name, or state directory across concurrent tests.
A test must preserve a pre-existing resource it does not own. Cleanup may remove only a resource created by that test whose resolved path and, where relevant, filesystem identity still match the recorded ownership evidence.
Tests may not download models, packages, runtimes, or other network content unless they are explicitly named live or acceptance commands. Routine tests install no dependencies and modify no trust stores.
Persistent logs, coverage, screenshots, or diagnostics are allowed only in a declared repository-ignored evidence directory selected by the invoking command. Evidence retained beyond that command or ephemeral CI workspace must have a manifest, size ceiling, expiry rule, and cleanup owner. Same-job normalized badge summaries are temporary comparison inputs and disappear with the job workspace. Raw c8 temporary data is removed after the declared reports are produced. Evidence must never contain credentials, protected data, temporary passwords, tokens, or production identifiers.
After each suite, a hygiene assertion must confirm that its resource registry is empty and that no owned disposable root remains. CI should fail on residue, not silently clean it and report success.
The suite supervisor must also compare repository state before and after, preserving every pre-existing tracked, untracked, and ignored item exactly. It must fail on newly created or modified content outside the declared evidence directory and inspect known ignored build, cache, and output roots; this independent check catches resources a test forgot to register.
If failure evidence must survive cleanup, copy only the minimal sanitized evidence to the declared evidence directory, report its path, and then remove the disposable execution root.

Native integration tests may create only uniquely scoped disposable native resources and must satisfy the same cleanup contract. Tests that change real services, accounts, registry or trust state, installation state, login state, or other protected machine state are explicit live or acceptance commands. They require a disposable target, a pre-test state record, a documented restoration procedure, and a post-test state comparison. If restoration fails, the test fails and reports the exact remaining state; it must never claim cleanup.

Test seams must use legitimate dependency injection. Production paths may not contain a NODE_ENV=test, simulation, authorization, signature, capability, validation, or privilege bypass. Child processes receive a minimal allowlisted environment rather than ambient credentials or unrelated workstation state.

Evidence kinds and runtime test types

1. Static conformance verification

Question: Does source, generated output, configuration, or an artifact have the exact required structure?

May inspect schemas, manifests, inventories, hashes, generated/source parity, command composition, source ordering where order is itself the contract, and compiler-visible declarations.
Must use a verify:* command or a clearly named conformance test.
Must not claim that a process launched, a UI rendered, an authorization check executed, or a native control worked.
Runs when its governed structural input changes and as an inexpensive prerequisite to the integration gate that consumes that structure.
Is not included in JavaScript behavior-coverage thresholds unless it imports and executes a reusable validator as its subject.

Reason to exist: Some properties—exact inventories, generated parity, canonical schemas, and launcher composition—are inherently structural and are cheaper and more deterministic to prove directly.

2. Unit test

Question: Does one deterministic mechanism produce the required result for all relevant branches?

Executes one exported function, class, validator, parser, policy evaluator, state transition, or serializer in-process.
Uses no real filesystem, network, child process, operating-system API, DOM, ambient clock, or ambient randomness. Values for those dependencies must be injected.
May use table-driven hostile, boundary, and equivalence-class inputs.
Runs while editing and on every push and pull request for the affected OS scope.
Is eligible for c8 native V8 coverage.

Reason to exist: Unit tests give the fastest, most precise evidence for logic and failure branches and make failures attributable to one mechanism.

3. Functional test

Question: Does one ARCANE OS capability or public boundary behave correctly through its real implementation?

Enters through the public API or protocol of the subject and exercises the real implementation inside that boundary.
May use a temporary filesystem, loopback transport, deterministic fake adapter, fake service, or bounded child process when that dependency is outside the declared subject.
Must not mock the subject under test.
Must cover successful behavior, authorization or validation denials, and the material failure/recovery paths owned by the boundary.
Must not change real users, services, installations, shell assignments, or protected machine state.
Runs for an affected capability during development; the complete portable OS functional set is part of the development CI gate.
Executed JavaScript is eligible for c8 native V8 coverage.

Reason to exist: Functional tests show that the public contract, policy, implementation, and controlled dependency seam compose correctly without the cost or risk of a complete machine journey.

4. UI integration test

Question: Does the real Shell or Provisioner UI present and operate one user journey correctly through its controller and frontend API?

Uses the real production HTML/controller and shared frontend API. A standards-compatible DOM harness may prove controller and semantic-state behavior; claims about a packaged artifact must load that exact built UI, and a real browser or supported WebView engine is required for claims about rendered layout, native focus, the accessibility tree, or platform behavior.
May stub the native/Core backend only beyond the UI boundary.
Asserts rendered state, semantic roles and names, keyboard and focus behavior, request/response wiring, progress, errors, recovery, and theme behavior that belong to the journey.
Source regular expressions alone are static conformance, not UI integration.
Runs when Shell, Provisioner, bridge, theme, shared UI primitives, or the affected journey changes. The complete set runs in explicit integration.
Is not a coverage gate by default; journey evidence is the objective.

Reason to exist: UI correctness depends on composition among markup, controller behavior, asynchronous transport, accessibility semantics, and visible state that pure logic tests cannot prove.

5. Portable system integration test

Question: Do built ARCANE OS components work together across real process, filesystem, RPC, packaging, or integrity boundaries without platform authority?

Uses generated or built Core/frontend/package artifacts and real local process or filesystem boundaries.
Uses isolated temporary roots and synthetic records.
May exercise framed RPC, encrypted broker protocols, package inventories, installation transactions, and failure injection.
Must not treat a simulated operating-system result as native-platform proof.
Runs for shared Core, bridge, packaging, integrity, privilege protocol, or platform-adapter changes and in the explicit portable integration gate.
Is not included in the ordinary coverage threshold; selected JavaScript may emit diagnostic coverage separately when useful.

Reason to exist: It catches composition defects that appear only across generated-code, process, filesystem, protocol, or artifact boundaries.

6. Native platform integration test

Question: Does a built or compiled ARCANE OS component enforce its contract through the real target-platform primitive?

Runs on the named target platform against compiled hosts, guards, services, packages, or distribution artifacts.
May use disposable named pipes, directories, processes, emulator profiles, and unsigned/development-labeled artifacts.
Does not require real participant data, production signing, a real user-login journey, or human approval of a protected action.
Runs only for the affected platform boundary, in its explicit platform gate, or as part of promotion preparation.
Is not a JavaScript coverage gate.

Reason to exist: Platform security and lifecycle claims cannot be proven by source inspection or simulation alone.

7. Acceptance test

Question: Does the exact candidate complete the supported real-machine user journey with the required operational evidence?

Runs on a disposable real host or an explicitly supported real-device test environment against the exact packaged candidate.
Covers applicable UAC or administrator approval, accounts, sign-in, services, publisher identity, hardware, real providers, assistive technology, installation, update, recovery, and rollback.
Preserves objective evidence and identifies every unperformed case.
Requires human participation wherever credentials, protected confirmation, assistive-technology judgment, or risk acceptance cannot be automated.
Never runs in the ordinary development gate.
Follows the release, security/privacy, and accessibility SOPs when ARCANE is explicitly promoted.

Reason to exist: Exact-host behavior and human journeys are the final proof for claims that controlled fixtures, simulation, and compiled probes cannot establish.

Profiles

Smoke profile

Question: Is the smallest critical path through the selected artifact alive, and does one critical fail-closed invariant still hold?

Selects a small named subset from functional, UI integration, portable system, or native platform integration tests.
Has an explicit artifact and purpose, such as smoke:os:portable or smoke:os:windows-host.
Must remain short enough to use as a rapid post-build or post-deployment signal.
Never replaces the complete suite for the boundary and never denotes a test type by itself.

Reason to exist: A small, representative profile can detect a broken build or environment quickly before investing in the full applicable gate.

Tags and evidence dimensions

The following describe what a test protects, not how it executes:

security: authority, identity, confidentiality, integrity, isolation, validation, secret handling, or fail-closed behavior.
privacy: data minimization, disclosure, retention, or identity separation.
accessibility: semantics, names, keyboard behavior, focus, announcements, contrast/theme compatibility, or non-color meaning.
regression:<id>: a verified prior defect with a focused reproducer.
recovery: interruption, rollback, retry, or reconciliation behavior.
compatibility: a supported version, format, or platform interoperation.
performance: a measured budget with controlled inputs and an explicit non-functional threshold.
platform:portable|windows|linux|android: the evidence environment.
destructive or protected-state: an acceptance-only warning requiring an explicit disposable target and authorization.

Required reason record

Every OS test file or parameterized test group must have an inventory record with these fields:

Field	Requirement
ID	Stable `OS-<area>-<number>` identifier.
Kind/type	`static` or one runtime test type from this SOP.
Subject/boundary	Exact mechanism or seam executed.
Requirement/invariant	Observable property the test proves.
Reason/risk	Failure that the test is intended to catch and why that matters.
Inputs	Representative, boundary, hostile, and failure cases.
Doubles	Every fake, stub, simulator, injected clock/random source, or temporary resource.
Resource effects	Files, processes, ports, pipes, environment, caches, or protected state created or changed.
Cleanup proof	How owned resources are closed, removed, and verified absent.
Platform	Portable or exact target platform.
Trigger	Source/artifact changes that require the test.
Evidence	Assertions and output that constitute a pass.
Canonical owner	Test that owns the invariant.
Related layers	Higher/lower tests that prove a distinct additional seam.
Profiles	Optional named smoke or other selection profiles; never a type.
Disposition	Keep, split, consolidate, replace, remove, or acceptance-only.

The catalog records every independently reported case or coherent parameterized matrix, not merely every file. Its validator fails closed on an unregistered test, orphan record, duplicate ID or canonical owner, missing reason, assertions, doubles, resource effects, or cleanup proof. It also rejects committed .only, unexplained skip/TODO cases, zero-assertion passes, unbounded timeouts, and retries that conceal a first failure.

A new test without a valid reason record cannot run in an ARCANE gate. A removed test must record the canonical replacement or explain why its requirement no longer exists. Tests with no material reason or no cleanup proof are removal candidates rather than templates for new work.

Doubles and fixture policy

A double is allowed only beyond the declared subject boundary and must be named fake, stub, simulator, or fixture so its evidence class is clear.
The subject itself must not be mocked.
Temporary filesystem use is a real filesystem boundary, not a mock.
Clock, randomness, environment, process identity, and host status must be injected or deliberately controlled when determinism matters.
Automated network tests use an isolated loopback fake. Live providers require an explicit opt-in acceptance or live-verification command.
A simulated result must say simulated in its data or evidence; it must never be promoted to a native or acceptance claim.
Security identity, privilege, signature, process-peer, and filesystem-identity claims must be tested at the nearest real boundary and receive native or acceptance evidence before the corresponding promotion claim.

Duplication policy

Tests are duplicates when they use the same effective input, execute the same boundary, and assert the same observable requirement. Different filenames, commands, or assertion syntax do not make them distinct.

Assign each requirement one canonical owner.
Consolidate equivalent inputs into one parameterized matrix.
Extract repeated harnesses and fixtures; do not copy protocol clients or setup logic across test files.
Permit overlap across layers only when the higher layer crosses an additional real seam or verifies an exact artifact.
A higher-layer test references the canonical lower owner and asserts only the integration-specific result.
Security or accessibility importance may justify testing the same requirement at another real boundary, but not copying the same source regex or simulated assertion.
Do not add tests merely to raise coverage. An uncovered meaningful branch needs a reasoned test; unreachable or platform-only code needs a documented exclusion.
Aggregate commands form a directed acyclic graph in which a selected case executes once. Catalog validation rejects duplicate case ownership and profile membership; focused command-contract tests separately enforce the package-script graph.

Coverage policy

ARCANE OS JavaScript coverage uses c8 and native V8 coverage. ARCANE does not configure or invoke a separate coverage runner or instrumenter; c8's transitive reporting libraries remain lockfile implementation details.

Aggregate unit and functional suites only.
Use explicit source ownership and --all so eligible unloaded files appear as zero coverage.
Exclude generated output, vendored code, test support, UI/system harnesses, native sources, and platform artifacts from the JavaScript threshold.
Publish text-summary, json-summary, and lcov reports for the complete coverage profile.
Establish a measured, trustworthy baseline after deduplication, then ratchet thresholds upward. Do not start with an arbitrary repository-wide target.
The initial clean baseline is enforced at 80% lines/statements, 89% functions, and 82% branches across the explicitly owned unit and functional sources. Raising a floor requires a newly verified baseline; lowering one requires a documented correction to source ownership or test meaning.
Require complete branch coverage only for small critical pure validators or finite state machines whose complete outcome space is demonstrably bounded.
A /* c8 ignore ... */ directive requires an inventory rationale showing the branch is unreachable, generated, or executable only in a separately tested native/platform environment.
Coverage must not cause a functional or system test to be copied into the unit suite.

The current source-bound baseline was measured by the exact unit + functional union under Node.js 22.23.1 and c8 11.0.0. It records 84.26% statements (3,271/3,882), 83.66% branches (1,004/1,200), 92.85% functions (221/238), and 84.26% lines (3,271/3,882). These are measured results, not restatements of the configured floors.

The dedicated ARCANE OS coverage evidence workflow is the sole CI owner of this explicit measurement. Relevant source changes trigger that path-filtered workflow, and workflow_dispatch also permits a deliberate rerun. Each job invokes npm run test:os:coverage exactly once, retains the same-job c8 reports and unit/functional summaries under the ignored tmp/os-test-evidence/coverage/ root, and then authenticates the tracked coverage-receipt.json and coverage.json endpoint against those results. The receipt binds an authenticated Git source revision, exact profile and covered-source hashes, the Windows x64 runner image, Node.js and c8 versions, floors, test cleanup result, and all four coverage metrics. The numeric Shields badge is a static presentation linked to that receipt, while the adjacent workflow badge reports current verification status; the unrelated Docs Pages deployment does not publish or authorize coverage evidence. The coverage lane remains explicit and separately owned: setup, smoke, npm test, the ordinary development check, and ordinary development CI never invoke it. The same dedicated job also verifies the tracked unit and functional endpoints against the normalized summaries produced by that one coverage-profile execution.

Testing-tool credit

A vanilla blossom and test checkpoints flow into Arcane OS geometry beneath the words vanilla-test plus ARCANE OS.

ARCANE OS proudly uses RIAEvangelist's vanilla-test 2.1.0 as the lifecycle tool for repository JavaScript tests. Its small, web-standard surface fits the one-case, one-lifecycle rule. Node remains the orchestrator, and c8 remains the separately owned coverage tool. The shared adapter creates one strict lifecycle instance per repository JavaScript case admitted through Node's test API. Node's strict assertion API supplies equality, rejection, and exception semantics because vanilla-test's comparison helper is coercive. The adapter settles each lifecycle exactly once, consumes its immutable report without printing a second ANSI report, preserves the original error and stack, and returns a normalized result. Node's central runner—not the case or assertion library—continues to own discovery, hooks, filtering, process isolation, timeouts, cleanup, concurrency, reporting, and exit status. No library-level process.exit() is permitted inside a managed case, and the separately owned c8 11.0.0 unit/functional coverage contract is unchanged.

Every managed set ends with a normalized summary containing total, passed, failed, skipped, duration, and cleanup status. README numeric badges are set-specific last verified views of normalized evidence and display N passed / M failed; the adjacent workflow-status badge reports whether the current main-branch development gate is green. A set without executable target evidence displays not run; it never displays zero failures as though that were a passing run. The managed runner writes no repository evidence by default. Evidence output is restricted to the ignored, owned tmp/os-test-evidence/ subtree. An evidence-owning workflow verifies its tracked endpoint byte-for-byte against the normalized result it just produced; ordinary development CI validates the tracked endpoint schema without regenerating historical evidence.

PowerShell, C, C#, Kotlin, and human acceptance procedures are not wrapped merely to claim library uniformity; their results are normalized into the same evidence schema. When an eligible canonical JavaScript functional subject executes in a child process, graceful shutdown and bounded reaping must allow V8 coverage to flush before aggregation. Generated Core, native, live, UI, and system lanes remain outside coverage thresholds unless a separately cataloged canonical source has a meaningful coverage owner.

Active layout and migration targets

The catalog, managed runner, unit, functional, UI, and portable-system directories are active. Native-system and acceptance directories remain migration targets until their target-specific profiles are implemented:

test/os/
  unit/
  functional/
  ui/
  support/
  catalog.json

machine_bundles/arcane-os-machine-bundle/test/
  unit/
  functional/
  ui/
  system/portable/
  system/windows/
  system/linux/
  system/android/
  support/
  inventory.json

Use names such as <subject>.unit.test.mjs, <capability>.functional.test.mjs, <journey>.ui.test.mjs, and <boundary>.system.test.mjs. Preserve Git history when moving an existing test. Static tools remain clearly named verify-* and are invoked through verify:* commands.

Commands and gates

Implemented commands are marked active; the remaining commands are the approved migration target:

Command	Contents	Default use
`test:os:unit` (active)	Complete currently migrated portable OS unit suite.	Focused unit verification.
`test:os:functional` (active)	Complete currently migrated portable OS functional suite.	Focused functional verification.
`test:os:coverage` (active)	Migrated unit + functional cases exactly once under `c8`.	Dedicated explicit coverage workflow, coverage review, and integration.
`test:os:ui` (active)	Shell and Provisioner UI journeys.	Affected UI/bridge changes and integration.
`test:os:system:portable` (active)	Built Core/RPC/package/integrity composition.	Affected boundary and integration.
`test:os:smoke` (active)	Four canonical public-API, Shell, Core-RPC, and integrity cases; no copied bodies.	Rapid development artifact health.
`test:os:system:windows`	Compiled Microsoft NT host/distribution checks.	Affected Windows/native work.
`test:os:system:linux`	Compiled Linux host/distribution checks.	Affected Linux/native work.
`test:os:system:android`	Built APK and emulator/instrumentation checks.	Affected Android/native work.
`test:os:acceptance:<platform>`	Exact-candidate real-host matrix.	Explicit promotion only.
`check:os:affected`	Path/contract mapped smallest trustworthy suites.	Local iteration.
`check:os:dev` (active)	Catalog and tracked badge-endpoint validation without coverage execution.	Ordinary push/CI.
`check:os:integration` (active)	Development gate + one unit/functional coverage run + UI + portable system + unique compatibility checks without rerunning managed cases.	Cross-boundary integration.
`check:os:<platform>`	Integration plus affected native platform gate.	Platform changes.

At the repository root, npm run check runs the rapid check:dev invariants and then selects test:os:unit exactly once. The pre-push hook and ordinary CI continue to use check:dev; coverage remains separately owned and is not reachable from either development command.

The future affected-test selector must broaden automatically for shared inputs:

Core template, method policy/contract, bridge, or shared runtime change: relevant units, all affected functional contracts, and portable system composition.
Shell/Provisioner markup, controller, theme, or frontend API change: relevant units/functionals plus affected UI journeys.
Capability, identity, privilege, integrity, installation, or recovery change: relevant units/functionals plus portable system and applicable native gate.
Build, package, manifest, signing, or native-host change: static conformance, portable system, and the applicable native platform gate.
Test selector or dependency-map change: complete scheduled integration until the selector change has independent evidence.

A scheduled complete integration run will remain the safety net once that selector is implemented. Until then, explicit workflow path filters and the documented development/integration commands own cadence; catalog trigger fields are descriptive inputs, not a claim that a general affected selector exists.

When implemented, affected selection must fail closed: an unknown or unmapped changed path selects the broader integration gate, never zero tests. It must print the path-to-suite reason and audit production files without trigger mapping before it can replace any current gate.

Migration order

Approve the taxonomy, current inventory, canonical owners, and duplicate dispositions.
Extract test-support mechanisms without changing evidence.
Add the shared disposable-resource registry and suite hygiene assertion.
Generate or refactor unit tests for exported deterministic mechanisms.
Measure unit coverage with c8; close reasoned branch gaps.
Generate/refactor functional tests around public OS boundaries and add their coverage to the ratchet.
Replace source-regex UI claims with rendered UI integration journeys.
Rebuild portable and native system suites around exact boundary ownership.
Nominate minimal smoke profiles from the resulting suites.
Preserve explicit acceptance matrices outside ordinary development gates.
When retiring a test, remove orphan fixtures, support helpers, snapshots, command references, coverage exclusions, documentation, and stale evidence; verify with a reference search and residue check.
Reconcile documentation and command composition, then measure wall time, flake rate, and coverage before and after the migration.

Application adoption

Applications may adopt this SOP without joining the OS gate:

create an application-owned catalog namespace and record a material reason, boundary, doubles, resources, cleanup, triggers, and canonical owner for each case or parameterized matrix;
keep business policy, prompts, content, and journeys in the application suite while importing shared OS mechanisms instead of copying their tests;
use synthetic identities/data and the same supervisor/residue contract;
put deterministic business logic in unit tests, one public application capability in functional tests, real rendered journeys in UI integration, and exact package/host composition in system integration;
apply c8 only to application-owned unit/functional JavaScript sources and ratchet from an honest baseline; and
expose named focused, development, integration, platform, and acceptance commands whose aggregate graph executes every selected case once.

Application changes must also follow app-building.md, including the shared-core/app-adapter boundary and focused development verification requirements.

Required handoff

For any OS test change, report:

requirement IDs added, changed, consolidated, or removed;
test type and why that boundary is the cheapest trustworthy proof;
doubles and evidence limitations;
resource effects, cleanup proof, and post-suite residue result;
canonical owner and any intentional cross-layer overlap;
focused command and result;
affected/full gate selected and why;
c8 coverage delta when unit or functional JavaScript changed;
native or acceptance work intentionally deferred under the development-only lifecycle.

Repository and reviewed source access