Repository documentation

ADR 0039: Bound the Remaining 1.1 Capabilities Before Implementation

• Status: Accepted
• Date: 2026-09-10
• Approval: Maintainer explicitly approved this ADR in the development conversation.
• Decision owners: literate-ai maintainers
• Release target: 1.1
• Numbering reconciliation: originally reviewed locally as ADR 0038; renamed during integration because upstream published the library-specific ADR 0038 first. The maintainer's approval and non-library decisions are unchanged. Additional library languages are governed by that accepted, implemented and qualified library decision.
• Roadmap: 1.1 SDLC audit delivery

Context

The maintainer requested an architecture/onboarding/intelligence/research assessment, actionable 1.1 work, and release preparation. That schedules the outcomes; it does not resolve the design choices in #280, #279, #365 or the plugin support matrix. ADR 0006 requires a real review before significant capability implementation. The maintainer explicitly approved this decision after review. The existing HTML Phase 0 acceptance remains in force.

The audit fixes can proceed independently: correct onboarding destinations and readiness wording, repair documentation, retain qualified artifact bytes, constrain MCP dispatch, pin CI dependencies, and automate mechanical skill maintenance. The local plugin packaging prototype is not a qualified or shipped capability.

Decision

Keep execution claims bounded

Amendment accepted 2026-09-12: ADR 0041 supersedes this subsection's local-development-only release scope with the full SEC-360 containment obligation. Existing local execution claims remain accurate until the new backends are qualified. The text below retains the original decision for historical context.

Ship 1.1 as explicitly authorized local development execution, not production multi-tenant containment. Keep independent acceptance and execution acknowledgements mandatory. State that same-user execution can access that user's host resources. Requests for unavailable isolation must refuse, not fall back silently. Qualified OS/VM containment remains a distinct, explicitly unsupported capability; requiring it for 1.1 instead changes this proposal and the release's acceptance workload.

Qualify two plugin adapters from one catalog

Generate Codex and Claude archives from canonical instructions, with the matching wheel version and exact source/catalog identities. Include every routed supporting skill; no independent normative copies, automatic hooks, credential material, marketplace registration or permission changes. Cursor and OpenCode plugin release adapters remain unsupported, distinct from their existing generation adapters. Require fresh-session discovery and a real independently accepted generated Component for each supported plugin before a release claim. Byte/manifest tests alone cannot satisfy that gate. The current local prototype must pass that review and qualification before landing as release-ready functionality.

Admit an importable library with an explicit support matrix

Define a provider-neutral library-artifact contract with named exports, argument and result contracts, qualified artifact identity, language/runtime/ABI requirements, and consumer binding. First qualify Python pure functions end to end; other language adapters refuse until separately implemented and qualified. This is the accepted first support boundary, not an assertion that #280 asked for Python only.

Run independent acceptance in a verifier-owned interpreter which imports the exact generated artifact and calls exports in-process. The consumer also imports that artifact normally; no per-call CLI/subprocess bridge. Starting an isolated verifier process does not turn library calls into subprocess-shaped consumer APIs. Exclude private oracle material from generation. Bind the consumer to tested artifact bytes, invalidate it on dependency/runtime drift, and never treat entrypoint absence as acceptance success. Keep portable-application unchanged. Prove import, negative cases, invalidation, clean regeneration, and retirement of one retained boundary.

Keep monorepo and submodule ownership distinct

For #365, expose detected build roots as candidates, not authoritative inferred Components. An acknowledged content-identified plan selects nonoverlapping roots, shared-source ownership and per-root harness commands before any movement. Reject ambiguous overlaps rather than duplicating source. Retain independent receipts and boundary-transfer state per selected Component; preserve single-wrapper behavior when no refinement is selected.

For #279, add an explicit orchestration profile that leaves .gitmodules, Gitlinks, child paths and child Git histories intact. Root authority names exact child commits and relationships, not copies of child authority. Plan/check are read-only; refresh requires a reviewed delta and refuses dirty/missing/unpublished children. Default conversion continues to reject nested submodules. Qualify initialized, uninitialized, shallow, absorbed and nested worktrees, rollback and clean-clone reconstruction.

For #368, refresh retained source scope through plan/acknowledged apply with exact old/new inventories. Preserve baseline/parity as history, invalidate current receipts and require requalification; do not pretend old evidence covers added files. Build this on the reviewed #367 promotion implementation rather than a competing rewrite.

Alternatives and consequences

Production isolation in this cut is a larger security/backend qualification program. Claiming all plugin clients or all library languages without acceptance would be misleading. Automatically splitting every detected directory risks overlapping ownership; flattening submodules destroys their intended boundaries. A consumer CLI bridge would not resolve the in-process library requirement.

Acceptance of this ADR authorizes these design boundaries, not weakened release gates, automatic model spending, source retirement without evidence, tracker closure, public publication, or external account selection. No existing 1.1 issue is silently deferred. These capabilities remain open release blockers until implemented and qualified; design acceptance alone does not close them.

Validation and order after acceptance

Finish ordinary authority/onboarding fixes; review #369; implement retained refresh and the two distinct adoption plans; implement and qualify the library adapter; complete the already accepted HTML Phase 1 slice; qualify fresh plugin sessions; then run exact-revision full CI, installed upgrade, artifact and collateral gates. Reconcile contributions and prepare the release only after all included work passes.