base-demo contracts are binding promises that should fail loudly when implementation, docs, demo behavior, or CI drift apart. This registry lists the highest-value invariants for the reference project and points each one at its source of truth and executable enforcement.
Update this file when adding a new durable invariant, expanding the representative environment, or changing demo behavior that other docs or tests depend on.
The release-aware capability inventory lives in the Base capability and evidence matrix. This registry records durable contracts; the matrix records the current Base release boundary, executable evidence, and intentionally deferred capabilities.
| Contract | Promise | Source of truth | Enforced by | Failure mode | Area |
|---|---|---|---|---|---|
project-baseline-required |
The project-baseline catalog entry remains present and required: true. |
services/catalog.json |
tests/validate.sh, tests/services_test.bats |
The baseline project health entry can become optional or disappear, making service checks pass while the project shape is broken. | Services |
http-health-url |
Every service with check.type == "http" declares a non-empty health_url. |
services/catalog.json |
tests/validate.sh, tests/services_test.bats |
HTTP checks cannot report a useful endpoint, or service status drifts from the catalog. | Services |
non-interactive-demo |
demo/demo.sh --non-interactive succeeds in the baseline CI environment. |
demo/demo.sh, base_manifest.yaml demo.script |
tests/demo_test.bats, .github/workflows/tests.yml |
The project-owned walkthrough becomes stale, interactive-only, or unable to prove the documented Base loop. | Demo |
manifest-trust-flow |
The user-facing Base loop reviews safe list/dry-run surfaces before basectl trust allow base-demo, and only then executes project-owned manifest commands. |
README.md, .github/workflows/tests.yml |
tests/validate.sh |
The Quick Start can drift from Base's fail-closed manifest-command trust model, causing first-run command execution to fail or encouraging unreviewed approval. | Security |
agent-ready-repo-guidance |
The repo demonstrates Base's agent-ready repository contract with a dry-run repo init --agent-ready preview and a real repo check . --agent-ready verification over AGENTS.md, skills.md, and AI context. |
README.md, AGENTS.md, skills.md, .ai-context/ |
tests/validate.sh, tests/demo_test.bats, .github/workflows/tests.yml |
Repo-local agent guidance can drift into hand-maintained files that Base no longer generates or verifies. | Docs |
language-profile |
project.languages declares the normalized Python, Go, Java, C, C++, and JavaScript profile represented by the committed fixtures; the list is metadata-only. |
base_manifest.yaml, services/ |
tests/validate.sh, tests/demo_test.bats, .github/workflows/tests.yml |
The representative environment can drift away from the manifest taxonomy, or the manifest can imply unsupported automatic toolchain setup. | Manifest |
environment-schema |
Every environments/*.json file is validated before use for exact top-level fields, HTTP(S) URLs, mode/operational consistency, logging values, nested booleans/ports, and service-catalog plus Compose references. BASE_DEMO_ENV=baseline remains a health marker distinct from the default services --env dev selector. |
bin/base_demo_environment.py, bin/base-demo-environments, environments/*.json |
tests/environments_test.bats, tests/validate.sh, demo/demo.sh |
Invalid nested configuration or unknown service/infrastructure references can reach lifecycle commands, or users can confuse Base activation health with deployment selection. | Environments |
environment-aware-services |
Every services operation uses the validated environment selection, and mutating lifecycle commands reject modeled non-operational environments before invoking Compose or processes. | bin/base_demo_environment.py, bin/base-demo-services, environments/*.json |
tests/environments_test.bats, tests/services_test.bats, tests/validate.sh |
Staging or production examples can start local dependencies, or commands can disagree about enabled services and requiredness. | Runtime |
uv-project-manager |
The project manifest opts into python.manager: uv, and the committed pyproject.toml plus uv.lock define the dependency-manager-owned project environment. |
base_manifest.yaml, pyproject.toml, uv.lock |
tests/validate.sh, Base-backed setup/check/doctor CI |
Base-demo can silently fall back to a Base-managed venv, leaving manually installed Python packages outside the uv drift contract. | Python |
uv-runner-command |
The uv-info command uses runner: uv in the manifest. |
base_manifest.yaml, src/uv-info.py |
tests/validate.sh, tests/demo_test.bats |
The runner teaching surface silently becomes an ordinary command and no longer proves command-level runner selection. | Manifest |
activation-owned-env |
.base/activate.sh owns the BASE_DEMO_ENV=baseline default for the green path. |
.base/activate.sh, base_manifest.yaml health.required_env |
tests/validate.sh, tests/demo_test.bats |
Health checks pass because unrelated shell state sets the variable, hiding activation drift. | Activation |
manifest-artifacts |
The manifest artifacts list stays non-empty and includes the bats-core tool artifact. |
base_manifest.yaml |
tests/validate.sh, demo/demo.sh |
Setup no longer demonstrates artifact reconciliation or the test tool prerequisite. | Manifest |
runtime-platform-env |
The env command prints BASE_OS, BASE_PLATFORM, BASE_HOST_ENV, and BASE_HOST with the other Base runtime values. |
src/env.sh |
tests/validate.sh, tests/demo_test.bats, demo/demo.sh |
Learners cannot discover the current Base runtime platform and host-environment contract from base-demo. | Runtime |
python-env-privacy |
The Python env command exposes only documented public Base diagnostics, renders secret-looking BASE_* names as [REDACTED], and the walkthrough sanitizes captured environment output before displaying it. |
lib/python/base_demo_cli/__main__.py, demo/demo.sh |
lib/python/base_demo_cli/tests/test_cli.py, tests/demo_test.bats, tests/validate.sh |
Project or workflow credentials can leak through direct inspection or the interactive and non-interactive walkthrough. | Security |
maintenance-prompt-safety |
The walkthrough inventories repo-owned prompts, displays the already-redacted config show output, and previews cleanup with clean --keep-last 1 --dry-run; it never renders a large prompt or deletes runtime artifacts. |
demo/demo.sh, README.md |
tests/demo_test.bats, tests/validate.sh, .github/workflows/tests.yml |
The reference walkthrough can leak machine-local configuration, become noisy or unstable from generated prompt contents, or delete local runtime state while demonstrating maintenance tooling. | Security |
installer-checksum |
Release-mode bootstrap uses the reviewed Base installer and commit selected by .release/supported-dependencies.json plus the base-demo v0.1.0 release commit, verifies the installer checksum, and refuses to move divergent existing checkouts. Explicit --dev or BASE_DEMO_DEV_MODE=1 reuses local contributor checkouts without pulling or switching revisions and visibly permits moving-source overrides. |
install.sh |
tests/install_test.bats, docs/release.md |
Two users can receive different bootstrap code, a release installer can execute an unverified input, or a contributor's feature branch can be silently switched or updated. | Security / Release |
service-log-permissions |
Process-backed service log files are created or corrected to mode 0600 before writes. |
bin/base-demo-services |
tests/services_test.bats |
Service logs can expose local process output through permissive file modes. | Security |
service-catalog-schema |
Canonical services/catalog.json and custom --catalog inputs use one validator for the root object, services array, object entries, safe unique names, and known scalar/nested field types; malformed input returns a field-specific usage error without a traceback. |
bin/base_demo_environment.py, bin/base-demo-services, services/catalog.json |
tests/services_test.bats, tests/environments_test.bats, tests/validate.sh |
Malformed user input can reach lifecycle code, expose Python tracebacks, or behave differently depending on whether the catalog is canonical or custom. | Runtime |
service-state-containment |
Canonical and custom catalog names are safe lowercase slugs; process state and log files remain direct, non-symlink children of the configured state directory, use mode 0600, and state updates replace complete temporary files atomically. |
bin/base-demo-services, bin/base_demo_environment.py |
tests/services_test.bats, tests/environments_test.bats |
Crafted catalog names or filesystem links can redirect lifecycle writes outside the state directory, expose process metadata, or leave partial state. | Security |
service-lifecycle-transactions |
Lifecycle plans validate before mutation; start stops at the first failure and rolls back invocation-owned process and Compose resources; restart preflights process ownership and never starts replacements after a stop failure; primary and rollback failures remain distinct. | bin/base-demo-services |
tests/services_test.bats, tests/infra_test.bats |
A failed command can continue starting later services, stop resources that predated the invocation, or launch a restart replacement alongside an instance it could not safely stop. | Runtime |
service-process-identity |
Process startup waits for survival and configured readiness, state records PID plus process-group/start identity, and stop refuses mismatched live PIDs. Native fixtures use owned-process health and claim no network port. | bin/base-demo-services, services/catalog.json |
tests/services_test.bats, tests/native_services_test.bats, tests/python_api_test.bats |
Startup can report dead services as running, stale PID reuse can signal an unrelated process, or never-started native fixtures can appear healthy. | Runtime |
compose-local-isolation |
Every published Compose port binds to loopback, Compose owns container names, and every Compose operation uses a stable checkout-and-environment project identity unless automation supplies a validated override. | infra/compose.yaml, bin/base-demo-services |
tests/infra_test.bats, tests/validate.sh |
Disposable credentials can become remotely reachable, or one worktree's lifecycle and log commands can target another worktree's containers. | Security |
frontend-setup-path |
basectl setup base-demo installs Node 22.22.0 with bundled npm 10.9.4 through mise, and basectl test base-demo delegates to a mise task that runs locked npm ci when frontend inputs change or dependencies are absent. |
.mise.toml, base_manifest.yaml, services/demo-console/package.json, services/demo-console/package-lock.json |
tests/demo_console_test.bats, tests/validate.sh, Base's external base-demo E2E |
A clean checkout can pass setup but fail the supported test path because Node, npm, Vite, or node_modules was never provisioned. |
Setup |
demo-console-build-gate |
macOS and Ubuntu CI install the locked frontend dependencies with Node 22.22.0/npm 10.9.4, compile the production console, run the Vitest/React Testing Library behavioral suite, assert entry artifacts, and fail the audit at moderate severity or higher. | services/demo-console/package.json, services/demo-console/package-lock.json, .github/workflows/tests.yml |
services/demo-console/src/App.test.jsx, services/demo-console/vitest.config.js, services/demo-console/build.sh, tests/demo_console_test.bats, tests/validate.sh |
Green validation can skip Vite or user-visible behavior, omit production artifacts, retain a known dependency advisory, or regress catalog loading/accessibility without detection. | CI |
security-scanners |
Required CI runs pinned Bandit 1.9.4 over project Python sources, pip-audit 2.10.1 against the locked uv export, and ShellCheck over tracked shell entrypoints. | .github/workflows/tests.yml, pyproject.toml, uv.lock |
tests/validate.sh, GitHub Actions security |
Shell or Python security regressions and vulnerable locked dependencies can merge without a dedicated required signal. | Security |
ci-trigger-deduplication |
Feature-branch commits run the validation workflow through pull_request only, push validation remains enabled for main, superseded runs cancel only within the same PR number or ref, and the validate, validate-base-cli-source, and validate-ubuntu job IDs remain stable. |
.github/workflows/tests.yml |
tests/validate.sh, GitHub Actions |
A PR commit can consume two full validation runs, unrelated branches can cancel one another, default-branch validation can disappear, or check names can drift. | CI |
full-live-http-validation |
The hosted full representative-environment lane provisions and verifies Go and Java, enables BASE_DEMO_FULL_VALIDATION=1, and requires positive live HTTP markers for the Go, Python, Gradle, and Maven APIs; the default local lane may retain explicit toolchain skips. |
.github/workflows/tests.yml, tests/validate.sh, tests/live_api_smoke.py |
tests/full_validation_prerequisites.sh, tests/full_validation_prerequisites_test.bats, tests/live_api_smoke.sh, GitHub Actions |
CI can report green while the representative API listeners or their launch toolchains were never exercised. | CI |
release-identity |
VERSION is the authoritative stable SemVer identity; Python/uv metadata, frontend package metadata, the Base-style top README badge strip and release links, and the changelog heading agree, and only an explicit matching annotated vX.Y.Z tag whose target is reachable from main can publish a GitHub Release. |
VERSION, pyproject.toml, uv.lock, services/demo-console/package.json, README.md, CHANGELOG.md, .github/workflows/release.yml |
bin/base-demo-release-check, bin/base-demo-release-provenance, tests/release_test.bats, tests/validate.sh, GitHub Actions |
Users, automation, or release provenance can disagree about the base-demo version, the current release can be hard to discover, the project-status strip can drift, or an unreviewed branch can publish a release. | Release |
ci-pinned-dependencies |
CI uses immutable full commits for the published Base and base-bash-libs contracts selected by .release/supported-dependencies.json, plus full SHA-pinned GitHub Actions. |
.github/workflows/tests.yml |
tests/validate.sh |
CI can drift with Base main, an older base-bash-libs release, or mutable action tags instead of validating the intended release capability contract. |
CI |
update-preview-boundary |
The walkthrough uses basectl update base-demo --dry-run only from a clean checkout whose current branch is provably the default branch; detached or feature-branch checkouts receive an explicit safe skip and never pull or run setup. |
demo/demo.sh, README.md |
tests/update_demo_test.bats, tests/validate.sh, .github/workflows/tests.yml |
A reference walkthrough can mutate a checkout, fail noisily in CI's detached state, or teach users to bypass Base's default-branch and tracked-clean safety boundary. | Product |
ubuntu-ci |
The repository has an Ubuntu job that runs basectl setup base --yes --no-notify, validates basectl setup base --profile dev --yes --no-notify, verifies bats/gh/shellcheck, and runs basectl check --ci base-demo --format json against the pinned Base checkout. |
.github/workflows/tests.yml |
tests/validate.sh, GitHub Actions validate-ubuntu |
Ubuntu support can drift from the documented Base setup, dev-profile, and read-only project health boundary. | CI |
platform-boundary |
README and CONTRIBUTING document macOS full-demo support plus Ubuntu/Debian and WSL2 read-only/development guidance for Base setup, dev-profile prerequisites, and project health checks, while keeping the coordinated release matrix and native-Windows non-goal explicit. | README.md, CONTRIBUTING.md |
tests/validate.sh |
Developers on Linux or WSL2 follow macOS-only project setup or demo steps without a documented boundary, or a component-level path is mistaken for the coordinated Base release contract. | Docs |
ci-json-check |
The demo shows basectl check --ci base-demo --format json and asserts JSON status output. |
demo/demo.sh, README.md |
tests/validate.sh, tests/demo_test.bats, .github/workflows/tests.yml |
The reference project stops demonstrating Base's CI-safe machine-readable check path. | CI |
onboard-continuation |
CI asserts the basectl onboard base-demo --dry-run preview reaches Check, Setup, Projects, and Trust, then executes the pinned Base test proving that a nonzero Doctor result still reaches Projects, Trust, and Next Steps and returns success when the later stages succeed. |
.github/workflows/tests.yml, README.md, pinned Base cli/bash/commands/basectl/tests/onboard.bats |
tests/validate.sh, GitHub Actions validate, GitHub Actions validate-ubuntu |
Onboarding can regress to stopping at a nonzero Doctor result, the demo can misstate the command sequence or exit behavior, or the preview can become README-only prose. | CI |
workspace-onboarding-agent-brief |
The demo and CI exercise basectl workspace onboarding and basectl workspace agent-brief against workspace.yaml.example so the peer base plus base-demo layout proves first-day and agent handoff readiness. |
workspace.yaml.example, README.md, demo/demo.sh |
tests/validate.sh, tests/demo_test.bats, .github/workflows/tests.yml |
Workspace-level onboarding and handoff commands can drift out of base-demo even though the repo already documents the peer-checkout layout. | Docs |
history-report-observability |
The README and demo exercise basectl history --project base-demo --limit 5 --report so base-demo shows Base's privacy-conscious local activity report. |
README.md, demo/demo.sh |
tests/validate.sh, tests/demo_test.bats |
Base's reportable local activity history can drift out of the reference walkthrough even though logs and plain history remain visible. | Observability |
github-workflow-hygiene |
Contributor docs demonstrate basectl gh issue readiness before issue-backed work and basectl gh branch stale during cleanup without making authenticated GitHub checks part of CI. |
AGENTS.md, README.md, .ai-context/overview.md |
tests/validate.sh |
base-demo can stop showing Base's own GitHub workflow helpers even though its contribution model depends on issue readiness, branch naming, and cleanup discipline. | Workflow |
tooling-testbed-boundary |
The tooling matrix separates active baseline tools, optional live wrappers, reference-only examples, Base-generated environment views, and blocked future Docker service support. | docs/tooling-testbed.md, README.md, .ai-context/overview.md |
tests/validate.sh |
base-demo can accidentally make external tools required, duplicate Base-owned behavior, or imply support before Base publishes the contract. | Docs |
base-generated-environment-reports |
CI runs basectl devcontainer base-demo --workspace .. --format json and basectl devenv-report base-demo --workspace .. --format json as read-only compatibility checks. |
.github/workflows/tests.yml, docs/tooling-testbed.md |
tests/validate.sh, GitHub Actions validate, GitHub Actions validate-ubuntu |
Base-generated environment reporting can drift or appear to require Docker, VS Code, Nix, devenv, or committed generated files. | CI |
optional-task-runner-wrappers |
justfile and Taskfile.yml remain optional wrappers that delegate check, CI check, test, build, demo, and service status tasks to basectl. |
justfile, Taskfile.yml, docs/tooling-testbed.md, README.md |
tests/validate.sh |
Task-runner examples can drift into a second command contract or become an undeclared setup requirement. | Shell |
reference-env-dotfile-examples |
direnv, asdf, chezmoi, and dotbot examples remain under examples/tooling/env-dotfiles/ and do not activate root shell or dotfile behavior by default. |
examples/tooling/env-dotfiles/, docs/tooling-testbed.md, README.md |
tests/validate.sh |
Reference tooling can accidentally mutate developer shell state, home-directory state, or the baseline setup/check/test loop. | Docs |
reference-multirepo-examples |
mani, gita, vcs2l, and west examples remain under examples/tooling/multi-repo/, aligned to workspace.yaml.example, and non-authoritative for Base discovery. |
examples/tooling/multi-repo/, workspace.yaml.example, docs/tooling-testbed.md, README.md |
tests/validate.sh |
External multi-repo examples can accidentally imply that Base imports, syncs, or owns those formats. | Docs |
When a change introduces a new promise between files, add a row here and make
sure tests/validate.sh or a focused BATS test fails if the promise drifts.
When deleting or changing a contract, update this registry in the same pull
request as the implementation and documentation changes.