ui-automation-control-plane

Reference: Runtime Storage Policy

This document is the human-readable storage policy for runtime-owned surfaces. It complements the generated governance references and explains the intent behind the current space-governance contract.

Runtime Root

• Canonical runtime root: .runtime-cache
• Repo-owned runtime data must stay under .runtime-cache unless a config explicitly documents a different path.
• Machine caches such as pnpm store, uv/pip cache, and Playwright browser downloads must stay outside the checkout; the authoritative repo-local Node root stays under node_modules.
• Repo-local install sandboxes such as .runtime-cache/pnpm-install-safe.* are drift, not valid steady-state runtime classes.
• Service-local runtime roots such as services/**/.runtime-cache are forbidden steady-state artifacts; repo-owned runtime data must resolve back to the root runtime cache.

Retention Tiers

Tier	Meaning	Default Cleanup Posture
evidence_keep	Current run, release, or audit evidence that may be needed to explain what happened	Keep by default; only clean via explicit higher-level retention policy
runtime_state	Active ledgers and stateful runtime surfaces	Validate active use before cleanup
disposable_generated	Reproducible generated outputs such as lint, coverage, and gate byproducts	Eligible for routine runtime GC
scratch	Temporary or bridge-only execution outputs	Most aggressive cleanup tier

Runtime Classes

• artifacts, reports, and backups carry evidence-heavy semantics.
• automation, dev, logs, metrics, and test-output are runtime-state surfaces.
• coverage, container-gates, docs-gate, lint-all, and test-results are disposable-generated by default.
• cache, temp, pytest-cache, and container-runs are scratch-style surfaces.
• Temporary mutation workspaces belong under .runtime-cache/temp/mutation-workspaces/...; mutation summaries and human-facing reports remain under .runtime-cache/reports/mutation/....

Shared Dependency Model

• Authoritative repo-local Node root: node_modules
• Repo-family fallback Node cache: ${XDG_CACHE_HOME:-$HOME/.cache}/uiq/node-modules
• Runtime bridge root: /tmp/uiq-runner/uiq-node-modules
• Explicit UIQ_NODE_MODULES_DIR overrides must still resolve to one of those governed roots. Parent-workspace spill paths such as ../node_modules are invalid current truth and must be rejected instead of silently reused.
• When UIQ_NODE_MODULES_DIR resolves back to the repo-local authoritative root, pnpm-facing modules-dir and virtual-store-dir exports must stay project-relative (node_modules, node_modules/.pnpm) so install flows do not materialize <workspace>/<absolute-path-without-leading-slash>/... residue under governed subtrees.
• bash scripts/tests/no-parent-workspace-node-modules.sh is the explicit local guard that fails closed when a legacy parent-workspace root reappears.
• Runtime bridges must not remain as dangling symlinks after execution.
• Successful container-gate runs must drop bridge-only runner-temp, node_modules, Python env, and browser-cache roots immediately after the gate exits cleanly.
• Successful container-gate runs must delete the current run’s .runtime-cache/container-runs/<gate>/<run_id> bridge immediately; stale bridges and gate breadcrumbs age out on the 3-day maintenance TTL.
• Docker-config staging under .runtime-cache/container-runs/uiq-docker-config is also scratch and must not survive beyond the same maintenance window.

Cleanup Boundary

• Routine runtime GC may operate on repo-owned disposable or scratch surfaces under .runtime-cache.
• ./scripts/runtime-gc.sh --scope all covers logs, runs, cache, backups, and extras in scratch / disposable_generated tiers only.
• ./scripts/runtime-gc.sh --scope automation is limited to pytest-* leftovers under .runtime-cache/automation.
• ./scripts/cleanup-runtime.sh --target .runtime-cache/container-gates --ttl-hours 72 is the explicit maintenance lane for stale container-gate run directories once the current proof loop has moved on.
• ./scripts/cleanup-runtime.sh --target .runtime-cache/container-runs --ttl-hours 72 is the explicit maintenance lane for stale runner-temp bridges and Docker-config sidecars.
• Repo-owned evidence or runtime-state surfaces such as reports, automation, dev, metrics, and test-output stay out of routine automatic cleanup unless an explicit higher-level retention rule says otherwise.
• ./scripts/cleanup-runtime.sh refuses runtime_state and evidence_keep directories even when they are targeted directly.
• Machine/shared external layers are audit targets, not repo-owned cleanup targets.
• Routine cleanup may select stale repo-local install sandboxes only after the implementation proves they are inactive and outside protected tiers; machine- shared external layers are never re-labeled as repo-owned cleanup targets.

Operational Constraints

• ./scripts/runtime-gc.sh and ./scripts/cleanup-runtime.sh require node on PATH to query governance metadata, but they must not provision shared node_modules, pnpm stores, or other dependency roots as a side effect of a cleanup run.
• scripts/ci/write-space-audit-report.mjs writes to .runtime-cache/artifacts/ci/space-audit-report.json by default, but callers may override the output path (for example in tests) so temporary audits do not pollute long-lived runtime state.

This site is open source. Improve this page.