Repository documentation
Design traceability
This matrix is the short map from product concepts to code and proof. Start here; read a deeper document only for the row being changed.
The newest explicit boundaries are the Component authority ladder, the executable-Component decision, and the production containment threat model. They deliberately distinguish implemented contracts from later planner and backend delivery.
| Concern | Constraint class | Authority | Enforcement seam | End-to-end proof |
|---|---|---|---|---|
| FreeBSD native workers | explicit guest/native OS identity and verified offline wheel closure; inventory is not lifecycle or hardware acceptance | os-freebsd Flavor; FREEBSD-001; framework issue 67 | private worker/matrix registration, native project/user paths, noninteractive SSH, named hardware and pressure queries, descriptor-bound storage; unsupported quota/GPU evidence stays unqualified | local wrong-OS/schema/initialization/pressure/release-selection tests and live SSH alignment plus hardware/storage/pressure receiver observations; exact installed-wheel lifecycle, retained custody, sandbox/toolchain realization and release matrix remain open |
| Retained secondary-account tests | reviewed account and resource scope with private defaults; privileged original tests remain trusted | RETAINED-USER-001; exact profile/worker/account/view policy and operator-private allocation inspector | fresh allocation inspections, actual read-only/nosuid views, eligible command activation/revocation, private-root restoration and cleanup-bound completed-run admission | eleven FreeBSD source checks pass without skips, including fixture orchestration and admission with a protocol-peer inspector; separate actual QEMU allocation-owner checks pass. Installed qualification, reusable provisioner and original-source lifecycle remain open; see the operator guide |
| Refresh input custody | nonexecuting local observations, not atomic ownership or publication | ADR 0039; exact root authority plus independent child state | refresh preparation reuses root lock validation and captures manifest/index/lock bytes and local node identities, HEADs, configuration digests and clean recursive child state; revalidation rejects drift | Real-Git preservation/refusal tests cover dirty/missing children, linked/absorbed Git directories, nested ignore settings, indirect/replaced inputs, retained writer markers, external filters and hidden index flags. Split indexes refuse before Git's timestamp write; publication/apply and full qualification remain open |
| Reviewed refresh authority delta | only explicitly selected commits may change; preparation grants no publication or write authority | ADR 0039 and SUBMODULE-ORCH-001; existing orchestration authority plus exact path/commit intent | RepositoryRefreshAuthority derives prospective pins and binds old/new authority and request identities, preserving all noncommit metadata and relationships |
Pure contract tests cover preservation, strict inputs, no-op identity, immutable records and no I/O. Filesystem custody, publication, acknowledged apply and end-to-end qualification remain unfinished |
| Persistent orchestration authority | root owns pins and declared dependencies, not child catalogs or local checkout state | modern ProjectDefinition.repository_orchestration; ADR 0039 |
typed immutable pins/relationships, canonical order and identity, closed modern schema; reject root catalog/output overlap and legacy-field admission | Manifest-store/schema round trips and public plan projection; initialization changes plan observations but not persistent authority. This contract does not implement initialization, current-pin verification or refresh |
| Explicit Gitlink orchestration plan/check | read-only exact observation, not child acceptance or publication | ADR 0039 and SUBMODULE-ORCH-001; stage-zero Gitlinks, byte-matching indexed/working .gitmodules, explicit consumer/provider declarations |
onboard orchestrate plan/check binds exact declaration bytes and bounded inventory; checks recompute reviewed identity, isolate ambient Git selectors and preserve independent child authority without implicit host/config/telemetry writes |
Real-Git inventory and public planning tests cover worktrees, shallow clones, nested ownership, configuration/pin/declaration drift and byte/mtime preservation. Initialization, root graph integration and refresh remain open |
| Intent refinement before lock | provider-neutral draft policy; draft is never generation authority | ADR 0013 contracts; litai design refine/explain/accept |
blocking questions prevent accept; no coding CLI | contract round-trip and CLI tests in tests/smoke/test_intent_refinement.py |
| Project taxonomy, documentation, and onboarding | repository/project policy | literate.project.json, declared Markdown, root SKILL.md |
declared-root enumeration, documentation identities/link admission, and litai project validate |
ambient-skill/doc rejection, renamed-root authority, and this repository validating itself |
| Project and generated-source intelligence | provider-neutral optional artifact contract; default product policy is provider none with every stage off. The same-user filesystem namespace is an explicit local TCB |
manifest source_intelligence policy; separate authority-source and indexed-mirror identities when a provider is selected; provider artifact is derived state, never source authority, a source-cache key, or a product gate |
init defaults to none; lifecycle validate/build/run/rebuild complete without a source-graph indexer | version/path/symlink/status/project/worktree/pending/error-redaction tests, untyped-bypass and identity-material mutation tests, default-none init/validate, default-none init/validate |
| Documentation authority freshness | human-review policy with exact integrity evidence | current project definition, onboarding skill, Component/Flavor revisions, exact skill graphs, workflow/routing catalogs, and normalized declared docs/assets excluding docs/roadmap/ |
exactly one literate-ai:authority-reviewed marker; non-writing project documentation-review computes the expected identity; documentation-review --record is the explicit recording workflow |
current/stale/missing/duplicate marker tests, queue-exclusion tests, and changes to authority and narrative inputs |
| Repository inheritance and initialized-project update | complete non-executing repository DAG plus recorded origin and content-addressed initialization baseline | sanitized direct-parent selection, every exact ancestor commit and project identity, per-file inherited Component/Flavor/skill/workflow/routing provenance, exact local bytes, current parent catalog at the target revision, and current installed scaffold | init --from uses isolated bare Git plumbing, composes descendant-over-ancestor catalogs including Component-global workflow/routing authority, and rejects sibling collisions; update re-resolves the complete chain and emits separate lineage/framework three-way plans; catalog-imported paths compare against the parent catalog, not the init template; conflict plans include ours/theirs diffs; --review-conflicts is plan-only; apply preserves conflicts by default, requires opt-in additions, admits only explicitly selected inherited-catalog conflicts through repeatable --take-upstream, retains only explicitly selected retired compatibility paths through repeatable --keep-local, compare-and-swaps lineage, validates once, and rolls catalog/provenance/lineage state back together; reparent changes parent authority explicitly and none creates a root; spec merge reverse-adopts one island without quarantine |
credential/cycle/truncation/collision/no-hook tests; three-repository init with inherited Component/Flavor/skill/workflow/routing and sample lock; catalog-vs-template classification; conflict-diff rendering; optional review; dependency-closed take-upstream and retired keep-local fail/rollback/success; spec-merge island without _legacy; upstream advance plus safe apply; local-conflict and missing-addition preservation; schema round trips; installed-wheel proof |
| Existing-repository conversion and retained harness | transactional adoption boundary; retained source stays authoritative until qualified replacement | exact source scope, detected commands, baseline and two parity records, lift-shift evidence; optional portable external sibling destination topology with operator-local locators excluded from project authority | init --convert quarantines only after preflight, copies source into below-project disposable roots, and uses one typed host adapter for explicit sibling links in baseline and both parity passes; project test-receipt run-retained keeps local controller-local or resolves a non-local ID through the private worker catalog, sends only bounded identity-bound retained source and inventory to a POSIX SSH receiver, and finalizes sanitized phase evidence after exact response validation; external sibling projections remain local-only and full remote evidence-bundle custody remains open |
exact rollback; wrapper/parity/source identity; bounded public mixed-stream tails, reported-storage hints, direct OS ENOSPC/EDQUOT classification and secret redaction; repo_man runtime-state exclusion; live-success/unmapped-failure/mapped-success sibling fixture; unsafe/overlap/collision/tamper/path-secrecy tests; retained map omission and success; local/remote selection, source/archive bounds, receiver failure/redaction, response tamper, platform and cleanup regressions |
| Operator adoption and brownfield release authority | one application service over existing mutators plus explicit evidence-bound conversion state | host preflight, content-identified create/adopt plan, .literate/conversion-authority.json, current receipt and Component-promotion evidence |
doctor is project-independent; onboard revalidates and acknowledges before calling init/convert; compare-and-swap stage edges are wrapped → retained → drafted → qualified; status composes existing readers; rebuild blocks adopted source until qualified |
JSON/TTY/missing-project/authentication tests; illegal-skip/forged-authority/noncanonical-state tests; conversion plan/write integration; installed-wheel create and adopt-to-retained golden paths |
| Forge-neutral tracker access and parent contribution checkouts | product policy distinct from lineage resolution and from release-gate --target |
Git remotes as tracker host authority; gh for GitHub issues/PRs/CI/land; glab for GitLab issues/MRs/CI/land; contribution working trees under parents/<id>/ |
litai project tracker inspect classifies remotes and names CLI argv including ci_status, land_create, land_merge, review_status, and issue_status; litai project peer-work surveys green reviews at cycle start and leftover worktrees at cycle end; agents invoke gh/glab; litai project parent checkout clones/updates with submodules and Git LFS and excludes parents/ from the child index |
URL classification including self-hosted gitlab-* hosts; inspect CLI; peer-work start/end tests; clone/update under parents/; nested submodule fixture; credentialed URL rejection |
| Durable user configuration, state, and institutional channel envelope | operator-local policy distinct from project authority and from MCP-as-catalog-kind | platform-resolved workers.json, mcps.json, project test.json, state observations/events; typed contracts; optional institutional_channels; global --discover-mcps default off |
user_paths.py owns OS roots; user_assets.py owns precedence/migration diagnostics; litai config paths/migrate expose them; agent skills author config while litai journals and fan-outs after mutagenic success |
simulated Linux/macOS/Windows roots; migration purity/conflict/symlink/idempotence tests; isolated config/state CLI tests; catalog/template skill parity |
| Prefix-installed CLI self-update | standing authorization for that make install prefix only; checkouts and CI stay inert |
ADR 0037; literate-ai/host-install-manifest@2 |
enrolled launcher stages GitHub Release wheels in the background and applies them on the next invocation of that same prefix | unit tests in tests/critical/test_host_self_update.py and uninstall of @2 plus staging |
| Native CLI and selected host toolchains | explicit stage-zero boundary; universal os-base; composable language/package/build/OS Flavor capabilities; tuple-specific host realization |
ADRs 0032 and 0033; flavors/os-base/toolchain.cdx.json; flavors/*/host-toolchain.cdx.json; flavors/os-*/host-install/<os>/<arch>/<accelerator>.cdx.json; pyproject.toml and lock remain Python-distribution authority |
dependency-free literate_ai.bootstrap SBOM parser; deterministic capability de-duplication/conflict rejection; centralized host tuple/OS-metadata policy; shell-free package/artifact query, consent, install, and re-probe shared by install_litai.py and worker bootstrap |
official CycloneDX validation, five tuple contracts, composition warning/conflict/provider/archive tests, local dependency preflight, and Ubuntu/macOS/Windows install plus selected-Flavor qualification |
| Project MCP catalog hygiene | project-owned servers distinct from operator opt-in, from embedded application MCP, and from in-page WebMCP | mcps/<id>/mcp.md; identity pins on catalog copy mcp:; reject secrets, reserved operator ids, generation-prompt operator MCP |
litai project validate fails closed on hygiene; litai catalog copy admits mcp: |
secret sibling, duplicate id, reserved jira id, generation-skill operator MCP, and mcp copy tests |
| Front-end, back-end, and WebMCP generation | specification-to-source skill inheritance plus Flavor-indexed ecosystems | nested mcp-application / frontend-application / backend-application skills; ui-react on implementation.ui-framework; application.web-frontend language slot |
recipe dependency pins; backend ecosystem indexer; lock eligibility and secondary constraints | tests/smoke/test_app_stack_skills.py; catalog/template byte identity; named Elixir skip |
| Claude/Codex plugin and in-process MCP adapter | distribution packaging distinct from project MCP catalog and from operator-catalog fan-out | .claude-plugin/plugin.json; make plugin-bundle; litai-mcp stdio JSON-RPC; Homebrew packaging/homebrew/literate-ai.rb |
bundle copies root SKILL.md and skills/agent/ only; MCP wraps typed literate-ai/cli-result@1 / cli-error@1; formula uses Python Virtualenv without CodeGraph |
plugin-bundle byte-equality, MCP initialize/tools list, Homebrew formula shape tests |
| Flavor mixin without re-init | project catalog mutation with fail-closed conflicts | litai flavor add; Flavor conflicts: both directions; shipped template Flavor trees |
copy Flavor/skill files, append default_flavor_selectors, invalidate component.lock.json; python+go mutates nothing |
linux mixin, python/go conflict, idempotent add, docker skill stamp tests |
| Authority learning proposal | evidence-only deterministic policy; drafting and admission remain deferred | exact derivation/build/test/acceptance/rejection evidence, sanitized signal/fact codes, pinned candidate owner sets, affected test suites, and rebuild Components | top-level litai learn RUN classifies exactly one narrow Component/Flavor/Skill/workflow/routing/framework/no-change proposal and performs no writes |
all dispositions, ambiguous cross-owner and missing-owner rejection, schema/identity round trips, private-value exclusion, one-proposal CLI envelope, and byte-for-byte no-mutation test |
| Application behavior | invariant boundary | one self-rooted component.md by default; explicit structured-provider roots plus a named local public interface when the provider does not express the portable call/result shape; optional named boundary/interface documents; repository conformance metadata separately pins an exact Component/specification/interface-bound private oracle |
public generation loads each selected specification and local/direct public-interface byte sequence once and cannot load verifier-labeled inputs; after artifact capture the verifier also creates one entropy-derived case in memory | every simplified sample Component parses and plans from its readable authority; the DMN/SCXML samples prove their public contract appears exactly once in bounded context; every binary passes the pinned cases plus a post-build runtime-generalization probe |
| Component lifecycle kinds | authored subclass contract; CLI argv is not the implicit base | optional component.md kind; omitted infers from entrypoints; reviewed inverse graph kind; CLI-only assumptions named in the authoring/lock boundary |
ComponentKind validation on authoring; inverse cli/library/service map; source promotion explicitly retains the zero-entrypoint library kind; declined batch/event/wrapped-source |
unit authoring round-trips for accepted kinds; source-promotion library-kind regression; explicit kind omitted from identity when empty; default init Flavors unchanged |
| Harness debug tracing | run-scoped diagnostics; debug generation is identity-bearing via the debug-spec-map skill |
--debug / --debug=FILE / LITAI_DEBUG; packaged debug-spec-map skill bytes |
stderr or truncated FILE NDJSON literate-ai/debug-event@1 for stages, redacted child argv, and spec maps; scanner-owned source/.literate/spec-map.json; Python helper on stderr only |
tests/critical/test_cli_verbose.py (redacted, bounded diagnostics) |
| Direct prompt-to-task translation | agent-skill plus deterministic CLI; no model call | skills/agent/prompt-master/SKILL.md; external task envelopes own their own translation |
litai prompt translate wraps prompt-master; --external-envelope and LITAI_EXTERNAL_TASK_ID (deprecated aliases --mac-envelope, LITAI_MAC_TASK_ID) fail closed |
prompt-master skill tests plus tests/smoke/test_prompt_routing.py |
| Readable layered specification context | authored product authority plus pinned conversion policy | self-rooted component.md; optional literate-markdown@1 child nodes with required name/summary/kind, path-derived ID/parent, explicit local references, and exact planning skills; Flavors and Component interfaces own nonlocal variation |
deterministic omitted-field defaults, strict frontmatter/path/reference validation, canonical effective-context projection, one-copy bounded prompt assembly, and generation-provider dispatch | all-sample semantic-content preservation; body-drift identity invalidation; VFI-shaped hierarchy/context tests; unknown-key, ID/parent mismatch, missing-parent, unresolved/cyclic-reference rejection; CLI recipe integration; skill dependency/pin validation |
| Required non-code assets | authored selector plus exact resolved bytes; immutable overlay boundary | component.md asset ID, component-relative/project:////HTTP(S) source, assembled path, role, media type, optional pin; lock-owned BlobRef |
pre-model reachability and pin check, repeated input-closure check, one exact locked asset tuple shared by planning and source materialization, streamed CAS admission, metadata-only generation context, asset identity in generation key, post-model collision-free tree merge | local binary and remote URI lock tests; missing/pin/change rejection; source runner proves binary CAS overlay is absent from coding-agent text and present in the exact source bundle; Standard sample regression proves planned and materialized asset identity sets are equal |
| Clean major rebuild and generated checks | invariant boundary; case-count limits are current policy | current base/Flavor specifications, exact skill closure, and exact bytes of generated source/tests/manifest.json |
new empty output, derived suite content identity, generated-suite validator, and provider-neutral test-generated port between build and acceptance |
missing/stale/malformed or substituted suite, runner drift, authorization-evidence, ordering, and failed-suite/no-commit tests |
| Source-only per-Component generation | invariant authority boundary; scheduling bounds are policy | exact prepared node, generation key/context/budget/prompt/recipe/workspace identities, and optional exact direct-resume candidate | typed GeneratedSourceCandidate/run output/provenance/checkpoint plus schedule_source_generation; canonical bounded layers, exact direct reuse, dependent cancellation, and no build/cache/publication authority |
closed-schema round trips, identity substitution, over-budget observation, reuse/invalidation, deterministic parallel order, and failed-provider cancellation tests |
| Authenticated inherited IDE-session generation | authenticated provider handoff with untrusted candidate output; no nested coding CLI | exact provider/session/key IDs; prepared request/plan/context/prompt/workspace/lock/recipe/model/output identities; authenticated ephemeral exact prompt bundle and workspace locator; nonce/deadline; source payload/tree, transcript, and provider evidence | InheritedSessionSourceGenerator plus create-once private directory transport/coordinator and generic Cursor stop.followup_message hook adapter; HMAC-authenticated request/context/response, current conversation/model/workspace verification, require_live_cursor_hook fail-closed when no stop-hook is present, single-owner terminal custody, source-only collection, no generated-source cache reuse, retained public handoff evidence, and verifier-owned Standard admission |
API/CLI selection, exact context availability/tamper, Cursor conversation/model/workspace/transcript binding, missing-hook inherited_session.current_session_unavailable, output confinement, IDE/coordinator roundtrip, authentication/session/request/source/evidence mismatch, unsafe/replayed channel, disconnect, timeout, cancellation, cleanup, stale/late/duplicate response, and successful source admission |
| Standard generated-source admission and worker continuation | verifier-owned invariant boundary distinct from downstream artifact acceptance | exact generated source manifest/tree/BOM/test suite; Component lock/plan/key/recipe; distinct component-orchestration and per-node planned coding-CLI request identities; Flavor and skill closures; coding-CLI tool/transcript; selectors; installed framework distribution; verifier test plan/results; exact attempt-scoped directory-custody identity | StandardSourceAdmissionEvidence and immutable source-only membership; bounded disposable source-test copies retain exact original membership and copied source bytes/modes while excluding test outputs; candidate/provenance bind both request identities while SourceDerivationCacheKey uses only the planned coding-CLI request; litai generate --admit executes source tests and publishes only matching membership; litai rebuild --from-accepted-source requires every planned member, carries explicit short-root custody through the worker CLI and Standard execution request without cwd/environment rediscovery, starts at indexing/object work, carries admission identity into downstream results, and has no generation fallback |
twelve-node shared orchestration with distinct planned requests; swapped-node, changed-orchestration, failed/changed tests and source, lock/plan/Flavor/framework/selector/provenance mismatch, transcript/schema/cache tamper, missing-member source_cache.runtime_absent, zero-generator worker continuation, greater-than-260-character checkout lookup exclusion, success/failure cleanup, and Linux/Windows wheel fanout |
| Standard lifecycle restart | non-authoritative recovery optimization with append-only evidence | exact execution plan, Component/generation/recipe identities, source-generation custody, immutable source blobs, stage subject, outcome, attempt, sequence, and predecessor | versioned Standard stage/checkpoint contracts plus filesystem CAS/head store; a restarted process rebinds source to its new workspace but must re-index, re-authorize, rebuild, retest, execute, and reaccept | schema/identity/status rejection, cross-store materialization and retry lineage, per-stage pass/failure ordering, zero-generator source resume, and real three-Component Bazel restart with build-cache hits |
| Concurrent target matrices | exact same-host cell isolation plus fail-closed aggregate evidence | deterministic Component/target/ordered-Flavor cell identity, cell-scoped lock and resolution audit, accepted source admission, lifecycle receipt, and exact aggregate cell set | each cell atomically materializes or validates its scoped lock before rebuild with the same selectors; rebuild must consume that exact lock identity; per-cell plan → lock → source-admission → lifecycle evidence and the aggregate reject missing, stale, mismatched, foreign, partial, or failed state |
fresh Linux/Windows/macOS lock-before-rebuild, same-Component isolation, deterministic concurrent creation, mismatched/unconsumed lock rejection, mixed-result aggregate rejection, and reduced large-declaration ordering regressions |
| Post-source build authority | invariant boundary | pre-source BuildRequestDeclaration; admitted generated tree/test/SBOM; distinct source-tree and source-bundle identities; current source index and grant |
host facade realizes one exact request/event and records provenance v4; Standard service creates authorization-free intent, indexes the tree, verifies a current grant for intent/request/index, then finalizes the composite build plan | declaration cannot name source; realization ordering, one-event resume/tamper tests; Standard intent/index/grant/finalizer substitution and diamond lifecycle tests |
| Bounded sample candidate replacement | repository conformance policy and fungibility pilot, not the generic repair contract | unchanged exact recipe and outer-planned derivation key, three-attempt maximum, and versioned rejection records: static Bzlmod validation binds run/generation/tree/source-bundle/suite/code; generated-test mismatch binds run/generation/build/suite/case/result; application/backend nonzero binds case/expected-result/role/return-code/stdout/stderr; C++ or Swift generated-source rejection binds run/generation/tree/source-bundle/suite plus the exact builder.cpp_generated_source_rejected or builder.swift_generated_source_rejected code |
the outer sample wrapper admits only: an exact terminal validate event and matching DependencyObservationError from the closed finite static Bzlmod allowlist with no admitted step; an exact generated-test mismatch; a typed application/backend host_execution.nonzero_exit during a generated implementation case; or a terminal validator-proven C++/Swift source rejection. Every attempt gets a fresh empty root; the next prompt receives only the prior sanitized typed rejection record, never its source tree or verifier facts; rejected workspace/cache admission is impossible, and exhaustion writes a content-identified envelope. Accepted retry prompts remain exact provenance while lifecycle membership binds the unchanged outer key only after stable-axis and ordered-rejection validation |
static Bzlmod allowlist retry versus resolver/evidence/unknown-code/admitted-step stop; exact process-evidence admission versus verifier/timeout/launch/auth/output/missing-evidence stop; typed C++/Swift rejection versus generic build failure stop; fresh-root, mixed-rejection, exhaustion, framework-stop, retry receipt closure, missing-chain, and stable-axis-drift proofs |
| Verifier acceptance | invariant boundary; concrete oracle format is repository policy | verifier-only oracle and independently computed post-build case | separate verifier closure plus provider-neutral verify-independent port; typed observation request/authorization evidence gates workspace preparation |
oracle exclusion evidence, fixed and entropy-derived result comparison, runner/evidence binding, and failed-verifier/no-commit tests |
| Full SDLC command and lifecycle driver | explicit project TCB constrained by invariant phase order | either a manifest-pinned external driver ID/version, sorted implementation paths and aggregate identity, argv template, allowed environment keys, timeout, scope, and phases; or the exact host-path-free installed wheel payload plus immutable versioned Standard policy; Standard execution additionally binds every plan node and selected Flavor's exact command profile to phase commands, either the optional //:litai_artifact Bazel target or the native Makefile/build-target profile, provider bindings, all build/compiler/runtime/launcher identities, and one observed recursive host-dependency graph |
litai rebuild verifies external project/executable/implementation/command authority or routes a declared Standard binding through the in-process filesystem composition; Standard selection resolves package, policy, and typed trust binding before allocation; the locked projector admits exactly one language and platform profile plus at most one typed Bazel or Make profile, discovers and drift-checks their declared toolchains, emits shell-free build/test/execute commands using --litai-test and --litai-smoke, and rechecks its lock and graph; Bazel uses its target-label adapter while Make invokes its exact generated Makefile with framework-owned output paths and a locked language tool, and incomplete profiles remain fail-closed |
unconfigured/mutated/escaping external driver, project drift, environment, host acknowledgement, incomplete evidence; Standard mismatch/editable/ambiguous/tamper and pre-allocation tests; canonical GitHub build-origin aliases, two-clean-install wheel identity and drift proof; all four real language strategies, Bazel target and native Make command/provider coverage, ordered PATH selection, executable drift, loose-plus-projected ambiguity, recursive host-toolchain observation, and installed-profile copying |
| Exact execution-worker routing | private non-authoritative routing plus immutable lifecycle authority; LitAI is not a scheduler | one exact local/SSH/command worker, target profile, declared parameters and hardware requirements; request binds Component/project/source/specification/Flavor/toolchain-requirement/model-scope identities plus an optional source-index identity, bounded runtime arguments and timeout; remote archive authority separately binds canonical paths, content, executable intent, and transport bytes; accepted-source continuation additionally binds one short attempt root and its build/object/runtime/receipt custody; Standard bootstrap binds the project-pinned Literate AI distribution identity and a target-specific canonical wheel manifest; worker bootstrap records no companion capability; result binds observed environment/toolchains, output/evidence, and immutable artifact reference | exact private-catalog selection; typed local and synchronous shell-free command adapters; bounded SSH archive staging excludes the explicitly bound coordinator build/object roots from authored source, carries accepted cache only in its separate verified archive, and carries the accepted manifest through receiver revalidation so Windows need not invent POSIX modes, then extracts and resolves every disposable lifecycle path under the explicit short root while project authority remains in the checkout; worker wheelhouse export resolves the coordinator-owned binary closure; worker bootstrap verifies distribution bytes before an offline native-environment install; command credentials enter only through declared environment bindings; successful build/test requires a credential-free durable artifact URI and content identity; run rechecks the shared authority identity before returning that artifact reference and arguments to the same worker |
contract/schema round trips, nullable GPU-memory/capability qualifiers, target/parameter/OS/model-scope contradictions, POSIX and Windows-like executable-mode round trips, missing/tampered/incompatible wheel and installed-payload rejection, real-wheel worker-equivalent Linux/Windows lifecycle preflight, launcher and rollback proof, output and authentication bounds, artifact URI/identity/staleness checks, synthetic command-worker build/test/run lifecycle, twelve-membership short-root restore with duplicate-source exclusion and cleanup, and packaged SSH Linux/macOS proof; same-revision Windows receipt remains open |
| CI shard and impact selection | operational CI-maintenance skill; not generation authority | litai project ci-plan; skills/agent/ci-test-plan |
detect frameworks; record maintained shard/impact mechanisms from issues #83–#86; fail closed to the full suite when an impact map is missing or untrusted; compose impact then shard; never silently no-op | pytest-split, Jest --shard, Go, cargo-nextest, Swift-unavailable, checkpoint keep-unsharded, and missing-map full-suite tests |
| Worker capacity observation | changing private inventory distinct from authored minimum requirements | one exact worker ID, observation time, OS, architecture, physical/logical cores, memory, GPU devices, and NVIDIA probe health | litai worker probe executes bounded platform-native local/SSH probes concurrently, validates a public typed schema, and atomically refreshes an ignored observation catalog; absent and driver-degraded NVIDIA states remain distinct; external dispatcher protocol, matching, and fleet scheduling remain outside this slice |
schema/contract round trips, dry-run/subset/atomic-write tests, malformed/timeout/protocol failures, and one real six-host macOS/Linux/Windows probe including healthy Blackwell and degraded Windows driver evidence |
| Worker resource-health admission and cleanup | accepted ADR 0043 and private health protocol; transient private health is separate from hardware inventory, execution authority and deletion authority | versioned four-role capacity policy, private storage-binding identity, worker/job/policy identities, bounded sample window and expiry, caller-available bytes, quota domains, inode status, sustained pressure policy, task-owned cleanup roots and exact cleanup authorization | pure capacity classification sums concurrent volume/quota demand and preserves shared reserves; bounded local/SSH/explicit-command storage probes retain nonce-bound custody; read-only Linux ext quota queries preserve independent domains; bounded local/SSH pressure receivers distinguish busy progress, sustained CPU/memory/paging impact, GPU memory pressure and allocation failure; lifecycle preflight, active polling and post-failure recheck hold new work without cancelling an active job; disk incidents trigger shallow bounded investigation; only proved-inactive exact targets can be proposed, and local apply revalidates current authorization before a configured no-shell tool and post-cleanup measurement | portable deterministic fixtures cover shared volumes/quotas, temp exhaustion, inodes, unknown probes, pressure/normal GPU/OOM classification, alert transitions, scan bounds, links, active-use uncertainty, authorization mismatch, changed targets, actual recovered capacity and bounded retry; native hosted and installed-wheel qualification on the final integrated head remains the release gate |
| Current project test receipt | compact local Git assertion plus project admission and repository history policy; authenticated external attestation is deferred | complete authority-review revision and a policy-pinned suite ID/version, exact runner identity, required evidence, and minimum test count, including source/resolved SBOM and current cache-lifecycle roles for full rebuilds | provisional driver assertion; Standard project-root aggregation binds every accepted root and exact lock after project/input revalidation; outer lifecycle/publication validation and finalized envelope at the supported API/TCB boundary; public raw/provisional rejection; bounded parser, atomic raw-receipt replace/check, release-only current gate, and ordinary Git commit | generated plus independent verifier execution, outer-side-effect isolation, raw-extraction rejection, unconfigured-policy/missing/current/stale/mismatch states, arbitrary-suite/empty-evidence/wrong-runner/count rejection, freshness, recursion/bounds, idempotence, exact-candidate tests, multi-root candidate/commit/CLI agreement and stale/missing member refusal |
| OS/language/accelerator variance | invariant boundary; concrete choices are policy | unique exact Flavor revisions plus an explicit Component-slot-to-revision relation | Flavor resolver plus unqualified +flavor/-flavor and repeated-axis +slot:flavor/-slot:flavor checks |
host OS × language sample matrix, Rust-backend/JavaScript-frontend plan identity, and one-revision/many-role resolution |
| Preferred alternative implementation providers | provider-neutral authored policy plus exact selected-Flavor override; mission provider IDs and capabilities remain project-owned | named Component provider_resolutions declarations with exact capability sets, required capabilities, preference, and fallback order; selected Flavor provider_overrides declarations |
filesystem lock planning invokes the canonical resolver, rejects unknown/ambiguous/insufficient overrides and unsatisfied requirements, binds exact results into the Component lock, and projects them through lock/plan CLI reports and every generation key | preferred/fallback/fail-closed/override/tie tests plus real Component/Flavor authoring-to-lock proof, catalog drift identity invalidation, and deterministic return to preferred |
| Bidirectional and distributed sample scope | proportional proof policy, not an application requirement | representative four-language host round-trip plus a versioned user-owned matrix of destinations, source modes, patterns, expected platform Flavors, canonical source manifest, exact Git commit, and digest-bound guard; the repository contains only a placeholder matrix | host-only live inverse tests; strict glob discovery; Git-visible working-tree archive parsed and identity-checked before source writes, or persistent Git object store with exact advertised-ref fetch and direct verified-blob materialization; portable path/link policy; implicit-submodule rejection; concurrent bounded SSH fan-out; remote platform assertion before generation/build/run | semantic spec parity for Python/C++/Rust/JavaScript on one host, malicious archive/path/symlink and Git-object/materialization tests, one three-level promotion/composition/regeneration proof, and the canonical four-language forward sample on user-configured macOS/Linux/Windows targets |
| Build-system preference and cost bounds | removable pinned policy plus non-authoritative optimization | build.system slot, ordered project defaults, exact native-Make and Bazel-preference Flavors/skills, selected-only derivation closure, separate catalog-audit identity, accepted derivation records, and actual build evidence |
initialized projects carry the pinned +flavor://literate-ai/build-make prompt policy; the weak default binds compatible exclusive roles; a slot alternative replaces one binding and unqualified -flavor://literate-ai/build-make removes all before effective-set and prompt assembly; Bazel remains an explicit selection for its sandbox/Bzlmod strengths, and forced regeneration returns no source-cache candidates |
default/reselection/alternative/removal/singleton- and multi-slot/absent-catalog tests, removed-skill semantic-identity stability, installed-scaffold and native-Make execution proof, prompt-text assertion, model-bound cache-key round trips, multi-result reuse, model-drift miss, and forced-bypass proof; the conformance samples explicitly retain Bazel where their harness requires it |
| Accepted generated-source cache | non-authoritative optimization with immutable-object and current-acceptance invariants; implemented by the external rebuild protocol and the reusable Standard service | outer-frozen planning manifest of exact recipe/plan/tool/model/request keys and Component-lock set, accepted derivation, generated files/tests, both CycloneDX SBOMs, typed repository resolutions, and exact per-key current lifecycle membership; provider artifacts are optional detached attachments and never source-key material; project manifest declares modes and project-relative/operator-bound targets | mandatory non-executing planning pass followed by exact manifest→control→decision→lifecycle set equality; cache-hit candidates and publication offers must each bind a lock in the outer-owned set before materialization/publication; pinned runtime/protocol directories; descriptor-relative bounded protocol I/O where available (explicit same-user named-path TCB on Windows); immutable filesystem-v2 CAS/membership; read-only non-mutation, including a canonical format-only Git representation as an empty miss while partial populated layouts fail closed; structurally verified source-only hits marked current-acceptance-untrusted; policy-driven final-path intelligence; aggregate receipt evidence derived from the complete member set; publication of current non-hits only after root packaging, packaged execution, and independent project acceptance; and a public SourceCachePublicationService plus filesystem project adapter shared by the CLI and product UIs for deliberate runtime-to-project promotion; the Standard service projects equal-key immutable source artifacts into current plan/request/root/recipe/workspace custody, then re-indexes, re-authorizes, rebuilds, retests, executes, and reaccepts without republishing the hit |
planning-request/project/driver/plan tamper, key omission/addition/change, foreign-lock cache hit/publication, evidence/tree/SBOM mismatch, provider re-index without cache-candidate duplication, hit re-publication, cross-application-root equal-key zero-runner reuse, changed-key rejection, root-boundary failure before publication, protocol replacement/recursion/bounds, corrupt objects, ambiguous target, missing or format-only read-only root, partial namespace rejection with exact path, path alias/overlap, materialization drift, forced bypass, idempotent replay through both the application and CLI seams, and reacceptance tests |
| Host toolchain requirements | pinned policy | closed, content-pinned Component inputs and selected Flavor toolchain contributions |
project-boundary/digest verification, typed constraint intersection, then adapter discovery | Python 3.11+/Node 20+ plans, conflict tests, and exact toolchain build/run evidence |
| Spec-to-code technique | pinned policy | exact skill manifests | skill digest and dependency closure resolution | plan output plus three-skill sample recipes |
| Existing source promotion | two explicit authority gates | exact source snapshot, signed reviewer-authored static graph or evidence-bound model-derived Component DAG, exact inverse skill/model-call journals when model-backed, complete source-free Component project, qualification execution profile/policy, and verified signed clean-run attestations | static review binds one complete source/evidence-closed Component graph and renders its public capability contracts; model translation retains its multi-node semantic graph and inverse custody; spec accept --project-target creates a standalone project while --integrate-project creates and identity-registers a native child beneath a retained adopted root; conversion authority rejects registry drift and coordinate collisions and aggregates projection evidence from the owning project boundary; spec qualify measures real forward generation/build/tests through a spec-only provider, keeps baseline execution in a distinct parity provider, signs the measured payload, then applies the pure release-authority rule |
static missing/unsigned/stale/incomplete graph rejection and retained-to-drafted public CLI proof; strict four-language response/journal/schema tests; library/CLI/service semantic fixtures and incomplete multi-node rejection; deterministic two-clean-run host parity per toolchain; live rich-spec → four generated/built/tested apps → four inverse specs semantic comparison; tainted-input/cache/provider/target/surface/attestation rejection |
| Dependency generation context | invariant boundary; source grounding is deferred on the public CLI | exact composed Component closure and pinned inputs | dependency recipe materialization | collision-free dependency documents and digest-drift tests |
| Repository-only source admission | invariant boundary; live acquisition remains product integration policy | target-neutral exact Git lock plus target-specific revision, Flavor set, toolchains, build plan, authorization, and path-bound outputs | injectable acquisition/index/planning/authorization/build/cache service; passing verification and admission require the complete canonical expected-path set | lock/plan/admission schema round trips, source/index/approval drift rejection, missing/extra/swapped/duplicate output-path rejection, and quarantine-cache proof |
| Software dependency inventory | CycloneDX wire standard plus complete-graph invariant | generated source/.literate/sbom.cdx.json, post-build SBOM evidence, the same exact resolved graph identity (normally the ComponentLock) and managed Component/repository-source graph in both, observed package/toolchain/runtime/system dependency facts, and the selected Bzlmod graph plus its raw lock/repository/query evidence |
official strict CycloneDX 1.7 validation plus canonical-byte, explicit-leaf, reachability, resolved-graph binding, managed-subgraph, bounded v1-name migration, pre-build manifest/lock/import VERS with inert JavaScript lexical projection, lifecycle-continuity, non-executing host-closure checks, and separate canonical Standard Bazel evidence/final-artifact manifests | malformed/partial/dangling/disconnected/nondeterministic/wrong-lifecycle BOMs, four-Component diamond preservation, changed resolved/managed graph, mixed legacy/current identity properties, source ranges, resolved exact versions, executable imports versus import-shaped comments/regex/strings/templates, dependency-free and transitive Bzlmod closure, evidence-byte tamper, cache round trips, and source-sbom/resolved-sbom receipt evidence |
| Model-stage order | pinned policy constrained by lifecycle invariants | pinned workflow | execution-plan compiler inside one source-generation runner; Standard scheduling treats the runner's result as source-only and begins a distinct post-source lifecycle | host plan → generate → realized request → guarded lifecycle assertions plus Standard source-schedule ordering tests |
| Model eligibility | pinned policy | pinned routing policy | model router and immutable route decisions | policy identity in plans; route identity in generation and run provenance |
| Lexical coding-model selection | nested authored preference below validation and routing authority | optional pipeline --model, Component and selected Flavor model-selection inputs, and selected specification-to-source skill models maps |
immutable parent-linked pipeline → Component → Flavor-role → skill-invocation bindings resolve independently per DAG node; equal-specificity disagreement fails before egress; the binding enters generation keys, recipes/prompts, source-cache identity, receipts, and typed worker dispatch | schema/contract round trips, CLI help, pipeline/Component/Flavor/skill precedence, sibling restoration, conflict rejection, provider command flags, model-bound cache misses, and installed-project forwarding |
| Coding-CLI transport and authentication | adapter policy with explicit non-hermetic limits | exact executable selection, provider clean/sandbox capabilities, and either machine-profile login state or provider-supported credential inputs | pre/post executable verification, provider-scoped launch/auth/transport environment allowlist, bounded prompt-free OpenCode --pure run --help capability preflight, OpenCode pure/clean deny-by-default configuration plus detached generation workspace, normalized authentication diagnostics, and bounded stream runner |
drift, environment scrubbing/credential forwarding, four-provider missing/invalid/expired-login classification, OpenCode 1.2.6-shaped capability rejection before model egress, supported OpenCode command/model/config/workspace custody, secret omission, exit-zero/no-tree handling, successful-tree non-misclassification, and output-overflow tests |
| Generated tree safety | invariant boundary; classification rules are policy | framework security policy plus the canonical portable source/ tree contract |
provider-neutral path/alias/ancestor admission before tree identity, then validation, generated-suite admission, classification, and build authorization | out-of-source, host-ambiguous, overlapping, unsafe, and invalid-suite trees are rejected before workspace truth; exact build grants remain required |
| Source acceptance | invariant boundary | exact generated tree plus passing generated-test and independent-acceptance results | both orchestrator gates precede the transactional workspace adapter | either failed gate prevents prepare/commit; accepted-tree identity equals generated files |
| Host execution | invariant boundary | explicit execution authorization | host runner process boundary | compiled output equals specified JSON |
| Release packaging and publication | invariant boundary; package shape, destination, actor, and invocation are explicit caller policy | successful exact Standard execution plan/result with its retained typed build plan, typed Component lock, versioned pre-package declaration, package result, retrievable accepted source-tree closure, canonical compact semantic-evidence manifest, security classification, and publication policy | create_standard_artifact_build_graph derives the only graph from accepted plans/exports; standard_release_evidence_identities derives the complete project/node lifecycle evidence index; ReleaseArtifactSet binds the source tree record, all child blobs, packages, and evidence manifest; create_standard_release_artifact_set reconstructs package plans and derives root/lock/target/workspace/resource authority; create_publication_request_from_release independently verifies the lock and derives revision/target/source/package roots plus compact provenance; StandardProjectReleaseService owns the effectful package/publish boundary; FilesystemStandardProjectRuntime.execute_and_publish requires an explicit release request and returns the accepted execution plus versioned aggregate receipt |
package/runtime-closure/schema round trips; logical-role/executable/package-output, forged-graph/declaration/lock/source-record/source-file/evidence-manifest substitution tests; immutable target-to-fresh-CAS source reconstruction; exact-lock pre-execution rejection; immutable manifest/import samples and external rebuild finalization tests |
The dependency direction remains:
contracts/domain ← application use cases ← ports ← adapters ← CLI or product UI
Filesystem discovery and coding-CLI commands are adapters. Project, skill, Component,
Flavor, identity, source-intelligence policy, and authorization values are neutral
contracts. Default product policy selects provider none. Workflow compilation
and generation orchestration are application services. Moving provider or filesystem
logic into a contract, or moving authorization into a skill, breaks this direction.
The shared port catalog contains only boundaries injected into a real application use
case and proven by a conforming adapter test; typed standalone services do not gain a
parallel generic protocol merely to appear hexagonal.
“Invariant boundary” means the authority relationship is stable; it does not mean every implementation detail is fixed. The constraint classification decision defines the terms and records the intentionally deferred guarantees.
When behavior changes, update the owning artifact, its public schema where applicable, the high-level flow if users see a different stage, and one test at the seam plus one end-to-end proof. Avoid documenting every class; document which authority makes each decision and where that decision becomes observable.