Repository documentation

0.9.0 executable-authority program

• Status: active
• Owning queue item: AUTHORITY-FACTORING-001
• Completion / archival evidence: closed for 0.9.0 on exact commit 5cf7100b1022a52127410e0da8797284be133217; all 15 hosted Linux, macOS, and Windows jobs pass in run 33858381265, with native worker and current-receipt evidence recorded in the owning queue item.

Outcome

Make the framework's documented taxonomy, dependency, deterministic-execution, and host-platform contracts executable through one Python authority at each boundary. Skills route judgment to those services instead of asking the model to reproduce mechanical work. This program implements ADR 0030 for the 0.9.0 release.

Ordered delivery

1. Restore release-blocking correctness

1. Keep make python-check hermetic. Inject the model preflight in selection-flow tests and prove that the ordinary gate launches no coding CLI or live model task. Retain explicit litai worker verify-model qualification.
2. Preserve declared optional dependency groups in self-host source authority. Admit a lazy optional import when declared, reject an undeclared import, and keep core-only installation and verification independent from optional packages.
3. Add a reviewed report/record helper for the sample test-runner source closure. The lifecycle driver already has one; the runner pin currently requires a maintainer to compute and edit a derived digest by hand, which allowed stale authority to survive.

These repairs are first because current HEAD cannot produce trustworthy broad-gate evidence until they land.

2. Make directory taxonomy one executable service

1. Add AgentSkillCatalog discovery, sentinel ownership, ancestor-chain, name/path/reference, symlink, and typed-dependency validation.
2. Replace changed-path prefix selection with catalog impact: owned resources map to their owner, parent authority changes include inheriting descendants, and typed dependency changes include transitive dependents or a stale-pin failure.
3. Materialize only owned closure plus explicit ancestor context for evaluation.
4. Use the catalog in project validation, authority-graph construction, initialization, and authoring normalization/migration.
5. Make the initialized skill set a declarative complete catalog or validated subset; remove dangling routes to convert-project, preflight-host-toolchains, and detect-before-install.

3. Centralize host/operator path policy

1. Add an injectable platform-family/path-policy value with semantic config, data, cache, state, managed-tool, install, temporary, and short-staging roots.
2. Implement ADR 0031's Linux/macOS $HOME/.config/literate-ai user-config root and Windows Roaming AppData Known Folder root, with project-ID-scoped test config and global worker/MCP config. Keep mutable observations/events in the separate state root. This explicit project convention supersedes the earlier tentative native macOS Application Support option.
3. Migrate user config and event state, tool bootstrap, installer/SSH resolution, Bazelisk custody, remote short staging, and repeated BUILD_DIR/OBJ_DIR fallbacks.
4. Ship the dry-run-first 0.8.x migration in ADR 0031. Detect legacy locations without silently merging conflicts. Preserve the existing remote path-length invariant.
5. Document standalone bootstrap and target-tool exceptions and add an AST/static gate against new ambient host-path policy outside the owner.

Implemented first slice (2026-09-01): user_paths.py owns injected OS roots and private directory custody; user_assets.py owns override precedence and migration diagnostics; litai config paths/migrate expose both. Worker, test, release, MCP, event, and sample consumers use these services. The supplied catalog was explicitly migrated and three reachable workers produced current observations; Windows validation awaits host-key trust rather than weakening SSH verification.

Completed audit slice (2026-09-01): the user-root policy is distinct from the smaller HostSystemPaths policy for os-release, AppArmor, ldconfig, and sandbox runtime or virtual roots. Linux/macOS/Windows table tests cover both surfaces. The AST gate now rejects ambient home and host-root environment reads plus absolute Path(...) literals outside the owner; remote target programs and dependency-free stage-zero code remain explicitly bounded exceptions.

4. Replace deterministic prompt work with connectors

1. Add shared application services and CLI/MCP adapters for work-item record/close, operator MCP write/discover, and channel trailer parse/ingest.
2. Add a typed NVIDIA stack compatibility resolver that consumes observations, locks, retained compatibility authority, exact versions, and hashes; leave policy ambiguity to the agent.
3. Expose document artifact inspect/verify around the existing deterministic scripts.
4. Add MCP resource list/read for skill ancestor chains, documentation, and packaged static resources; do not duplicate CLI business logic in the server.
5. Thin convert-project, record-user-directed-work, select-nvidia-accelerated-stack, configure-operator-mcp, ingest-channel-work, and document-authoring skills to routing and judgment.

5. Make native installation declarative

1. Treat GNU Make and the already executing compatible Python as stage zero. Model the remaining native CLI prerequisites separately from the pinned PyPI closure.
2. Add a universal flavors/os-base/toolchain.cdx.json, selected Flavor host-toolchain.cdx.json mix-ins, and CycloneDX 1.7 realization SBOMs beneath flavors/os-<family>/host-install/<os>/<arch>/<accelerator>.cdx.json, including package manager, package IDs, artifact pins, probes, command templates, and graph edges.
3. Route make install through a generic detector/query/consent/install/re-probe adapter. Interactive consent is one prompt; noninteractive installation requires LITAI_INSTALL_DEPENDENCIES=yes.
4. Fail unsupported tuples with the detected tuple, supported inventory, SBOM root, and porting instruction. Do not guess a fallback or bootstrap a missing manager.
5. Validate the actual operation on Ubuntu, macOS, and Windows CI.

Acceptance contract

• The ordinary Python gate performs no model/network operation; explicit live qualification remains fail-closed and separately tested.
• Optional declared imports and undeclared imports have distinct, tested outcomes; self-host replication reaches its intended source-drift assertion.
• Lifecycle-driver and sample-runner pins can both be reviewed and recorded through deterministic commands, and version checking rejects stale closures.
• Parent, child, owned-resource, template, and typed-dependent skill changes produce the expected impact set. A projected parent cannot absorb child sentinels.
• A freshly initialized project has no unresolved skill references, and catalog/template parity or subset membership is mechanically enforced.
• Table-driven tests cover Linux, macOS, and Windows roots, relative-XDG rejection, redirected Windows folders, overrides, legacy migration/conflict, short staging, and event-state separation on any development host.
• Wheel/zip static resources continue to load through importlib.resources.
• Connector contract tests prove schemas, lifecycle transitions, errors, and MCP/CLI parity without invoking an LLM for deterministic transformations.
• Every host-prerequisite SBOM validates as CycloneDX 1.7 and matches its path tuple; dependency decline changes nothing, consent executes only declared commands, and unsupported tuples name the SBOM porting directory.
• A clean-checkout make install succeeds on Ubuntu, macOS, and Windows using the tuple's declared native manager and an isolated host-native or explicit prefix.
• Focused tests pass first, then make python-check, make skills-check --all, project validation, and the exact release commit's Ubuntu/macOS/Windows CI matrix.
• The operator-declared literate.workers.json CPU/GPU Linux and Windows workers are probed through litai worker and run applicable platform shards without recording credentials, private hostnames, or raw routing configuration.

Scope boundaries

This program does not rewrite working source-generation subsystems, require optional packages in core environments, replace logical repository paths with host-native ones, or centralize target/kernel protocol constants into host config. Live generation and semantic document composition remain model work; parsing, custody, identity, schema, and deterministic verification do not.