Defines the portable manifest format for declaring authority-gated repository surfaces.
A protected surface is one where the technical capability to change it is not sufficient authority to change it.
Access control can grant the capability to perform an operation. It does not by itself establish that the capability is sufficient authority to modify a protected repository surface.
Accountable Surfaces records where capability is insufficient authority, and binds each crossing of that gap to required human review, supporting evidence, and permitted AI participation.
This repository defines the structure and conformance rules for:
.accountability/surfaces.toml- protected surface declarations
- surface object and role structure
- review and evidence requirements
- AI authority limits
- manifest self-protection
- declared-vs-satisfied obligation checks
- enforcement mappings to existing external mechanisms
This repository is the source of truth for the accountable surface manifest format. It does not define all vocabulary terms directly. Vocabulary terms are defined in the accountable authority, surface, review, and evidence vocabulary repositories.
Technical capability is not authority.
Repository surfaces that carry authority-bearing roles must be declared explicitly, reviewed explicitly, evidenced explicitly, and enforced externally.
Draft v0.1.0.
The specification is intentionally repository-first. It is validated first against concrete software and theory repositories before any broader portability claim is considered.
| Repository | Purpose |
|---|---|
accountable-authority-vocabulary |
Permission, AI authority level, denial state, and revocation terms. |
accountable-surface-vocabulary |
Surface object, surface role, downstream effect, and reserved lifecycle-gate terms. |
accountable-review-vocabulary |
Review kind, review scope, reviewer authority, and review satisfaction terms. |
accountable-evidence-vocabulary |
Evidence, verification, attribution, and attestation terms. |
| Profile | Purpose |
|---|---|
repository-protected-surface |
General repository profile for protected files, directories, commands, workflows, generated artifacts, and releases. |
lean-theory-repository |
Profile for Lean theory repositories with public theorem surfaces, reference artifacts, generated contracts, and validation commands. |
uvx accountable-surface-spec validate --path .accountability/surfaces.toml --strictPython tooling is used to verify internal consistency and generate artifacts.
Show command reference
Open a machine terminal where you want the project:
git clone https://github.com/structural-explainability/accountable-surface-spec
cd accountable-surface-spec
code .uv self update
uv python pin 3.14
uv sync --extra dev --extra docs --upgrade
uvx pre-commit install
git add -A
uvx pre-commit run --all-files
# repeat if changes were made
uvx pre-commit run --all-files
# validate SE manifest
uvx se-manifest-schema validate-manifest --path SE_MANIFEST.toml --strict
# validate accountable surface manifests
uv run accountable-surface-spec validate
uv run accountable-surface-spec validate --path .accountability/surfaces.toml --strict
uv run accountable-surface-spec check-examples
uv run accountable-surface-spec export-schema --check
# do chores
uv run python -m pyright
uv run python -m pytest
uv run python -m zensical build
# save progress
git add -A
git commit -m "update"
git push -u origin main