contracts.md

Base Contracts

Base contracts are documented promises that should fail loudly when behavior, docs, tests, generated guidance, or workflow policy drift apart. This registry maps the first high-value contracts to their source of truth and executable enforcement.

Use this page during product reviews and large review-batch triage. If a finding says "the docs say X but the code does Y", add or update a contract row before treating the fix as complete.

Contract Registry

Contract	Source of truth	Enforced by	Failure mode	Area
GitHub workflow policy	GitHub Workflow, CI Supply Chain Policy, .github/workflows/*.yml	tests/test_github_workflows.py, tests/test_issue_branch_policy_workflow.py	Workflow permissions, concurrency, timeout, token, supported Python, or generated-guidance policy drift	CI
Workspace manifest repository URL policy	Workspace Manifest, cli/python/base_projects/workspace_manifest.py	cli/python/base_projects/tests/test_workspace_manifest.py	A documented accepted URL form is rejected, or an insecure http:// repository URL passes silently	Workspace
Workspace manifest source policy	Workspace Manifest, cli/python/base_projects/workspace_pull.py	cli/python/base_projects/tests/test_workspace_pull.py	workspace.manifest_source accepts cleartext HTTP or overwrites a local manifest after an invalid fetch	Workspace
Project installer template integrity	Project Installers, templates/project-install.sh	cli/bash/commands/basectl/tests/repo.bats	The maintained installer template downloads and executes a Base installer without honoring configured SHA-256 verification	Security
Base-owned remote shell installer policy	Remote Installer Policy, cli/python/base_setup/remote_installers.py, standalone Homebrew entry points	tests/test_remote_installer_policy.py, cli/python/base_setup/tests/test_remote_installers.py, focused Homebrew BATS tests	A Base-owned installer bypasses the registry, its documented URL drifts, or a managed uv/mise override executes unverified or different bytes	Security
CLI local log file privacy	Local Observability, base_cli/logging.py	base-cli/tests/test_logging.py	Persistent CLI log files are created with permissive permissions, exposing command details before Base can restrict them	Security
CLI docs, help, and completion drift	Command Quick Reference, .ai-context/COMMANDS.md, bin/basectl, shell completion scripts; audited behavioral references below	cli/bash/commands/basectl/tests/docs.bats, cli/bash/commands/basectl/tests/help.bats, cli/bash/commands/basectl/tests/completions.bats, tests/test_command_reference_flags.py	Public help, docs shortcut behavior, command reference, AI context, or completions no longer match the shipped command surface	CLI
Project demo script contract	Project Demo Workflow, Python Manifest, cli/python/base_setup/demo.py	cli/bash/commands/basectl/tests/demo.bats	A declared demo.script is treated as a shell command, escapes the project root, accepts an invalid path, or loses passthrough arguments	CLI
Public command and JSON stability tiers	Stability Tiers, Command Quick Reference, Doctor Finding IDs	tests/stability_compatibility.py, tests/test_stability_compatibility.py, tests/test_stability_tiers_docs.py	Public command tiers, source-owned help contracts, JSON compatibility rules, or stable finding ID guarantees drift from the accepted v1.8.0 provenance baseline	Product
Workspace agent-brief JSON schema	Workspace Manifest, schemas/workspace-agent-brief.json	tests/contracts/test_workspace_agent_brief_schema.py	basectl workspace agent-brief --format json no longer conforms to its published schema	Workspace
Workspace update JSON schema	Workspace Manifest, schemas/workspace-update.json	tests/contracts/test_workspace_update_schema.py	basectl workspace update --format json no longer conforms to its published schema	Workspace
Workspace test JSON schema	Workspace Manifest, schemas/workspace-test.json	tests/contracts/test_workspace_test_schema.py	basectl workspace test --format json no longer conforms to its published schema	Workspace
Workspace status JSON schema	Workspace Manifest, schemas/workspace-status.json	tests/contracts/test_workspace_status_schema.py	basectl workspace status --format json no longer conforms to its published schema	Workspace
Read-only inspection JSON	Inspection JSON, Command Quick Reference	cli/bash/commands/basectl/tests/inspection-json.bats, cli/python/base_release/tests/test_engine.py, base-cli/tests/test_inspection.py, tests/test_stability_tiers_docs.py	A scoped command emits prose or invalid JSON, changes the v1 envelope, loses finding/error semantics, or diverges from text-mode exit policy	CLI
Project metadata defaults	.github/base-project.yml, GitHub Workflow, Repository Baseline	cli/python/base_github_projects/tests/, cli/bash/commands/basectl/tests/gh.bats, cli/bash/commands/basectl/tests/repo.bats	Issue defaults, Project field options, or repo-visible Project configuration drift from the Base Project schema	Product
Canonical positioning documentation	Product Requirements, Product Assessment, Why Base, and the canonical introduction surfaces	tests/test_contract_hardening.py	A canonical newcomer, contributor, or agent surface reintroduces retired product positioning or drops the accepted local-operating-contract thesis and outcome loop	Product
Adopter golden path	Base Adopter Golden Path, First-Mile Bootstrap, Upgrading Base, Manifest Command Trust, and GitHub Workflow	tests/test_adopter_golden_path_docs.py, cli/bash/commands/basectl/tests/update.bats (upgrade behavior; prose completeness still needs review)	Installation, upgrade, or the first verified project PR becomes ambiguous, hides trust or platform boundaries, or loses actionable recovery guidance	Adoption
Native Windows support boundary	Native Windows Support Contract, README.md, canonical product/context docs, and .github/workflows/windows-contract.yml	tests/test_windows_support_docs.py	A public surface or release note claims native Windows support before the launcher, command subset, and clean-install gates exist	Platform

Audited Behavioral References

The October 2026 reconciliation adds the following document-to-behavior map. These existing tests cover implementation behavior or selected documentation assertions; they do not enforce every sentence or prove documentation completeness. The correction PR also passed both repaired YAML examples through the production parsers using temporary fixtures. Recurring extraction of those examples and complete source-to-document coverage remain future guardrail work.

Maintained contract	Implementation and existing validation	Coverage limit
Project Python triggers and static versus opt-in verification	cli/python/base_setup/project_routing.py, cli/python/base_setup/test_requirements.py; their tests in cli/python/base_setup/tests/	Behavioral routing/inspection coverage does not validate every duplicated explanation.
IDE mutation consent	cli/python/base_setup/ide_installs.py; cli/python/base_setup/tests/test_ide_installs.py	Explicit consent behavior is tested; prose/recipe completeness needs review.
Earlier-BOM release recovery	cli/python/base_release/; test_release_readiness.py, test_release_publication.py, and test_engine.py in that package's tests	Supported recovery gates are covered; release procedure ordering still needs review.
Uninstall retention	cli/python/base_uninstall/engine.py; cli/python/base_uninstall/tests/test_engine.py	Resource selection/removal is tested; the project-run versus Base-history split was additionally checked with a disposable fixture.
Workspace deadlines and cancellation	cli/python/base_projects/workspace_process.py, workspace_setup.py, workspace_test.py; matching tests in the package	Process/setup/test behavior is covered; platform-specific escaped descendants and all signal combinations are not promised.
Registry example and manifest overview	cli/python/base_setup/registry.py, manifest.py; parser tests in the package	Actual fenced examples were checked for this correction; no continuous fenced-example extraction is claimed.
Review governance, package ownership, contributor and AI guidance	tests/test_contract_hardening.py, tests/test_command_reference_flags.py, tests/test_documentation_links.py; package census reviewed in #2629	Selected assertions and links are checked; full ownership/semantic parity remains a review responsibility.

Contract Check Runner

Default Python validation includes the top-level Python contract tests. That means python -m pytest in CI and ./bin/base-test in a source checkout fail when GitHub workflow policy or the contract registry drifts.

Run the focused cross-surface contract slice with:

tests/contracts/run.sh

The runner intentionally composes existing focused tests. It is not a replacement for the full suite. Use it when:

• a review batch reports docs/implementation drift;
• a change edits workflow policy, public command docs, generated guidance, workspace manifest policy, or project installer behavior;
• a PR needs a fast contract-focused signal before broader validation.

Review Finding Taxonomy

Classify future review findings before opening issues:

• implementation bug: shipped behavior is wrong even if docs are silent.
• docs/implementation drift: docs and behavior disagree.
• missing regression test: a fixed bug has no focused test.
• missing policy test: a documented policy has no executable guard.
• duplicated helper/API drift: parallel helpers disagree or invite inconsistent fixes.
• stale generated artifact: generated guidance, completions, or exported context is out of date.

This classification should appear in issue bodies for review-driven findings. It keeps future passes focused on the failure mode instead of producing another undifferentiated backlog.