README.md

scripts

scripts/ contains operator-facing wrappers and repository validators for abyss-stack.

These files stay at the source root because deployment sync copies them into the runtime Configs/scripts/ command surface. Mechanic pages own the meaning and part routes; this directory owns stable command entrypoints.

All operator command files at this root are thin wrappers. The implementation bodies live under the owning mechanics/<package>/parts/<part>/ routes and are still synced into deployed Configs/ with the wrappers.

Command Groups

Group	Commands	Owning route
Layout and sync	aoa-install-layout, aoa-sync-configs, aoa-bootstrap-configs, aoa-check-layout, aoa-first-run	config projection, runtime lifecycle; implementations under mechanics/config-projection/parts/{bootstrap,sync}/ and mechanics/runtime-lifecycle/parts/{layout-install,first-run-bootstrap}/
Lifecycle wrappers	aoa-up, aoa-down, aoa-warmup, aoa-status, aoa-logs, aoa-wait, aoa-smoke, aoa-install-systemd, aoa-ovms-admission	runtime lifecycle; implementations under mechanics/runtime-lifecycle/parts/{start-stop,logs-status,wait-smoke,user-unit}/
Compose introspection	aoa-preset-profiles, aoa-profile-modules, aoa-profile-endpoints, aoa-render-services, aoa-render-config	config projection rendering; implementations under mechanics/config-projection/parts/rendering/
Diagnostics	aoa-doctor, aoa-diagnose, aoa-internal-probes, build_diagnostic_surface_catalog.py, validate_diagnostic_surface_catalog.py	diagnostic spine; command backends under diagnostic-spine and runtime-lifecycle parts
Machine fit	aoa-host-facts, aoa-machine-bridge, aoa-machine-fit, aoa-platform-adaptation	machine fit; command backends under mechanics/machine-fit/parts/
Inference pilots	aoa-qwen-run, aoa-qwen-check, aoa-qwen-bench, aoa-llamacpp-pilot, aoa-langgraph-pilot, aoa-local-ai-trials, aoa-tos-foundation-lab, aoa-long-horizon-pilot, aoa-bounded-autonomy-pilot, aoa-runtime-bench-index	inference pilots; command backends under mechanics/inference-pilots/parts/
Governed execution	aoa-governed-run, aoa-agent-os-runtime, aoa-external-actor-bind, aoa-external-codex-agent, aoa-external-codex-incarnation, aoa-external-codex-stasis, aoa-export-memo-candidate, aoa-export-runtime-evidence-selection, aoa-export-artifact-hook-candidate, aoa-run-memo-contradiction-integrity	governed execution; command backends under governed-execution and runtime-repair parts
Federation, KAG, and RPG seams	aoa-federated-check, aoa-sync-federation-surfaces, aoa-routing-canary, aoa-routing-cutover, aoa-kag-runtime-family, aoa-kag-runtime-projection, aoa-kag-runtime-eval, tos-up, aoa-tos-graph, aoa-rpg-runtime-projection	federation seams; command backends under mechanics/federation-seams/parts/
Repair adapters	aoa-a2a-return-closeout-dry-run	runtime repair; command backend under mechanics/runtime-repair/parts/
Repository validation	ci_gate.py, validation_lanes.py, run_pytest_lane.py, validate_stack.py, validate_nested_agents.py, validate_local_stats_port.py, validate_decision_records.py, generate_decision_indexes.py, build_workspace_decision_graph.py, validate_workspace_decision_graph.py, release_check.py	root AGENTS.md, validation command authority, local stats port, mechanics artifact topology, decision records
Windows bridge	aoa.ps1, aoa-doctor-win.ps1, aoa-bootstrap-wsl.ps1	machine-fit windows bridge

Contract

• Keep command names stable unless the route cards, docs, validators, and deployment sync behavior move with the change.
• Keep thin wrappers and part-local backend paths aligned; validate_stack.py treats this bridge as a required topology contract.
• Keep source checkout and deployed runtime paths distinct.
• Keep aoa-routing-canary non-canonical: isolated and live-canary materialization require exact trust inputs, existing targets require a rollback root, and rollback preserves the displaced candidate.
• Keep aoa-routing-cutover receipt-bound: it accepts only an exact runtime trust verdict, public-release record, materialized owner-switch receipt, named host change, and atomic predecessor rollback root. It never authorizes repository archival.
• Use aoa-install-systemd --all-user-units when the deployed Configs mirror should become the source path for every allowlisted working user unit without restarting those services.
• Use aoa-install-systemd --provision-mcp-http-auth as the explicit, non-printing secret action before starting authenticated shared MCP owners.
• Use aoa-install-systemd --rotate-abyss-stack-mcp-auth only as a standalone stopped-unit transaction; it leaves consumer refresh and canary restart explicit.
• Use aoa-install-systemd --system-units only through pkexec or an equivalent privileged route, and only for the allowlisted support units under systemd/system/managed-units.txt.
• Keep wrappers public-safe and avoid printing secrets.
• Keep decision-record shape, indexing, and generated decision graph validated through generate_decision_indexes.py --check and validate_decision_records.py when docs/decisions/ changes.
• Use python scripts/build_workspace_decision_graph.py --write to refresh the ignored local workspace graph under Logs/decision-graph/latest/ when an agent needs cross-repo decision nodes and edges.
• Use python scripts/build_workspace_decision_graph.py --check to fail fast when that local workspace graph is stale.
• Use python scripts/validate_workspace_decision_graph.py to validate the workspace graph schema, JSONL parity, counts, local cache freshness, repo source-posture projection, and coverage contract. This route does not fetch remotes or prove remote freshness.
• Keep lane command sequences in docs/validation/validation_lanes.json; ci_gate.py and release_check.py read that manifest instead of owning duplicate command lists.
• Keep the complete pytest selection behind run_pytest_lane.py: automatic mode uses at most four process-isolated workers over a measured default of 16 file-aware shards (smaller selections retain a soft target of 92 tests per shard), proves their exact disjoint union against one baseline collection, and supports exact serial rollback through ABYSS_STACK_TEST_SCHEDULER=serial. Automatic mode keeps targeted arguments on the serial path; the existing --scheduler process-4x32-file-aware route may process a targeted selection using the same exact partition proof. Effective stateful options such as --sw and non-executing options such as --collect-only, --setup-only, --setup-plan, --fixtures, --fixtures-per-test, --cache-show, --markers, --version, or --help use the serial path even when supplied through PYTEST_ADDOPTS or config addopts; non-executing runs retain native pytest cache semantics. Relative -c/--config-file and --rootdir paths are resolved from the repository root, matching the working directory used by each child. Shard output is written to a durable log and tailed without waiting for descendant-owned descriptor EOF; failed shard logs are replayed at aggregate closeout for bounded-log diagnostics, and tests are not retried. The runner disables third-party pytest plugin autoload by default because this lane owns its process scheduler and does not use those plugin fixtures. For an explicit external plugin contract, use PYTEST_DISABLE_PLUGIN_AUTOLOAD= (an empty value) to opt out; pytest treats any non-empty value, including =0, as the disable flag. Each shard now writes its own temporary pytest cache; the parent combines failures into pytest's ordinary lastfailed cache once. Unfinished or unaccounted shards remain conservatively eligible for retry, fixed selected tests are cleared, and failures outside the selection are retained. -p no:cacheprovider still disables this local hint. No cached result is reused by the full lane, and no automatic retry is added.
• Keep validate_local_stats_port.py as a thin delegation to the aoa-stats contract owner; do not copy the central schemas or validator into this repo.
• Keep validate_nested_agents.py responsible for every discovered inherited AGENTS chain, including unmodeled and legacy cards, and preserve its 32-KiB fail-closed budget when route-card topology changes.
• Put mechanic-specific implementation logic under the owning mechanics/<package>/parts/<part>/ route when it can move without breaking operator command stability.

See AGENTS.md for editing rules.

release_check.py uses synthetic Configs parity by default so source release audits do not depend on the current machine's live runtime mirror. Use python scripts/release_check.py --parity-mode live only when deliberately checking /srv/AbyssOS/abyss-stack/Configs.