Repository documentation

Literate AI 1.3 integration

• Status: active
• Owning queue item: RELEASE-INTEGRATION-004
• Completion / archival evidence: pending scoped implementation and qualification

The 2026-10-18 sweep of jordanhubbard/literate-ai found 20 open issues and three open dependency PRs at main 77fcd039. Nineteen issues already name milestone 1.3. Include the unassigned target-specific Python admission issue #65 because it blocks legitimate cross-platform retained applications and belongs with the Python dependency work. Inclusion records an obligation, not completion. The distribution is already 1.3.0 in development; do not bump it to repair prose. No release tag, package publication, or collateral publication is authorized by this development pass.

Execution order

1. Prioritize #47, the milestone's named highest priority: importable Python libraries with verified offline wheels, relocated packaged acceptance and tamper refusal on Linux and Windows. Then address #65 and #48.
2. Repair test/gate determinism and cost (#53, #56, #27); preserve fail-fast, checkpoint custody and all declared evidence. The retained work/56-parallel-gate-tests tip 45673801 is already an ancestor of main; it contains no additional implementation to merge.
3. Complete operator fixes (#3, #44, #49–#52, #46) and target realization #43.
4. Qualify the carried-forward update, dispatch, package, native-CLI and worktree programs (#2, #4–#7). ADRs 0046 and 0047 are accepted in current repository authority (2026-09-25); stale carried-forward issue text still calls them Proposed. Their remaining implementation and qualification contracts stay binding.
5. Reassess #24 against current package/audit evidence; remove the temporary exception only when its acceptance is actually met.
6. Refresh collateral and perform exact-revision release gates only after the implementation scope and release scheduling decision are complete.

Issue scope

Open pull-request landing queue

All three reviews were non-draft and green at the sweep. Inspect each diff and land through the normal exact-revision gate; prior green heads do not qualify a later combined revision.

Remaining readiness blockers

The initial sweep had no current 1.3 machine-readable dispositions, even for issues assigned to milestone 1.3. Record fresh include dispositions and repeat the sweep after integration. Two missing, prunable temporary worktree registrations remain unresolved; preserve their commits and audit through WORKTREE-002 rather than force-remove them. Historical 1.1/1.2 queue evidence does not prove 1.3 acceptance. The release policy's milestone must be 1.3.

First implementation batch

• Python library wheel lifecycle (#47): isolated build/test/import, relocated independent acceptance after removal of source/artifact/wheelhouse, and missing retained output, dependency manifest/payload and both SBOM refusals. The 12 focused Python evidence/projection/lifecycle tests pass locally without skips. Native Linux/Windows qualification and consolidated integration remain pending.
• Documentation scan (#53): real Git fixtures ignore generated/untracked output while preserving tracked edits; exported trees use the directory-walk fallback. The complete documentation gate passes 21 Node tests and renders 121 diagrams from 605 tracked Markdown files before the new plan is staged.
• Audit exception (#24): OpenSpec 1.14.3 removes the braces chain; exception list is empty. Nine overlong requirement paragraphs were split without removing any normative sentence. Both change sets pass strict validation. The audit retains five low findings, with zero high/critical findings.
• HTML (#49/#50): public render/commit/verify passes and semantic version changes still make the view stale. Real Chrome desktop/mobile checks pass selection, zoom, fit, no overflow and no page errors. Desktop canvas matches the expanded inspector at 1,096 pixels; mobile retains its 350-pixel canvas.
• GPU memory (#44): authored POSIX and Windows serializers preserve unavailable memory as null; device parsing accepts it without discarding other observations. Positive memory and query failure remain explicit fixture controls. Local POSIX coverage passes; native Windows and consolidated qualification remain pending.

All 20 issues and PRs #60–#62 now have matching 1.3 include dispositions. No issue is claimed closed by this checkpoint.

Source admission and diagnostics batch

Issues #51 and #52 now have focused repairs: empty source generation uses the existing bounded/redacted transcript path for both output streams and reports its selected isolation profile without retrying a deterministic refusal. Python inventory policy static-checkout-inventory@2 uses a complete inert AST only to disprove exact assignment matches whose values contain no literals. Secret literals (including numeric literals), private-key filenames, uncertain languages and invalid syntax remain excluded. Entirely excluded static inventories return workflow.inventory_excluded before synthesis.

The 20 coding-CLI tests and 28 source-related tests pass locally. The existing SSH diagnostic implementation for #3 now has explicit tests of host-key, changed-key, authentication, DNS, refusal and timeout causes, worker attribution and a mixed healthy/failed catalog; all four worker capability tests pass locally. Consolidated qualification remains pending.

Qualification checkpoint

The first batch's exact code passed 18 selected tests without skips on native Windows (311d1e6b) and native Linux (b6629508). The difference between those revisions is the installed version-health smoke assertion. make wheel-check installed-e2e passes at b6629508, including a non-editable wheel, the stable version-health projection, declared HTML currency and the offline command-worker journey. These are bounded development proofs, not a 1.3 release attestation.

The combined implementation is retained at 0668f24f in draft PR #66. Full local Python and exact-head hosted qualification were started there; they remain unproven until completed. The final policy correction changes repository pre_release_version from stale 1.2 to 1.3 through litai release state set, matching the existing distribution version and contribution milestone. It does not prepare, tag or publish a release. Renew final-head CI after this metadata commit.

The expected remaining implementation programs are #4–#7, #27, #43, #46, #48, #56 and #65. Issue #2 already has a three-way implementation and historical qualification, but still requires current integration and versioned publication; it remains open. No current scope item is silently deferred.

A fresh real SSH check on the combined source proves #3's first-contact boundary: an isolated empty known-hosts file with strict checking returns the named worker's exit-255 host-key refusal; its ordinary registered route then produces a valid hardware observation. The source tests also retain the healthy result beside a separate failed route. No saved host-key policy or worker registration was changed.

The source-inventory exemption received an adversarial mixed-file review before landing. A safe assignment must not hide credential dictionary values, keyword arguments, function defaults, annotated literals, embedded JSON or private-key material elsewhere in the same file. Whole-file inert literal checks now precede assignment exemptions. All 30 source-related tests, including five credential regression tests, pass locally. Final-head native and hosted gates must include this additional hardening.

Parent README workflow

Issue #46 now has a reusable maintain-parent-readme skill in maintainer and initialized-project instructions. After a successful initialization, adoption, update or reparenting transaction, agents run its installed Python helper's read-only plan and authorized apply. This is an agent workflow follow-up; the initialization and reparenting commands do not silently write an extra README. The helper uses validated direct-parent selection and lineage, represents multiple direct parents, preserves authored prose outside its managed block, and refuses local-only identities until an explicit browser URL is supplied. Eight local regression tests pass, including a real initialized/reparented project and exclusion of example links in comments/code. Skill validation, documentation and integration qualification remain required before landing.

New peer work found during execution

A repeat sweep found issue #67 and draft PR #68 on feat/freebsd-workers (afa2e503). Include this peer work in 1.3 under its existing FREEBSD-001 owner. The draft covers worker identities, registry/schema plumbing and bounded native probe fixtures; it explicitly lacks OS Flavor, toolchain/alignment, storage, installed-wheel lifecycle and full native release qualification. Its existence proof and current artifact/receipt acceptance remain required. Do not merge it as completed FreeBSD support from mocked dispatch coverage. Both entries have matching include dispositions and milestone 1.3. The current scope is therefore 21 open issues, three dependency PRs, integration PR #66 and FreeBSD PR #68.

Refresh revalidation cost

Issue #27 now retains two independent complete observations at preparation and then re-reads exact bound file bytes/signatures, nodes and current authority instead of rediscovering an unchanged Gitlink graph at every custody boundary. Plain local/worktree configuration retains only signatures and content digests; included configuration still uses fresh Git resolution. Packed objects and shared worktree registries likewise retain fresh Git fallback. Index flags are reused only after complete index bytes match their validated baseline.

The reported armed-stage failure journey passes with 427 actual Git subprocesses in 8.9 seconds, including fixture setup. A real-Git regression enforces at most 500 launches. All existing 24 refresh tests pass in 210.8 seconds; expanded input coverage passes seven tests including index, HEAD, loose/packed refs, Gitlinks, worktree registrations, common-store locators, manifest/config/include drift, packed-object corruption and credential-free configuration custody. The new budget test also passes. Final combined native, full-suite and exact-head CI qualification must still complete before landing.

The earlier combined 0668f24f completed 1,492 local Python tests with 37 platform/environment skips. f652bdd3 independently passes installed-wheel/offline E2E and 34 selected tests without skips on each native Linux and Windows worker. Those revisions do not qualify the later refresh optimization.

The parent-README workflow uses the installed litai project parent-readme front door so isolated installations do not depend on ambient Python imports. The thin CLI route discovers the canonical selected project, keeps read-only planning and explicit apply, and shares the existing browser-override parser. Ten focused tests pass, including public CLI planning/apply/idempotency and missing-project refusal. The installed-prefix smoke exercises the same route through the actual launcher. The core candidate b7269a9f separately passed all 1,506 local Python tests with 37 platform/environment skips in 2,819 seconds; the CLI correction requires its own current-source qualification.

Second implementation batch

The first batch landed through PR #66 at 5d92797a. Candidate 0990bd76 passed all 26 hosted CI jobs, complete local Make shards and non-editable installed E2E. The local suite reported 1,508 tests and 37 skips; nine additional discovered methods belong to one unavailable-Elixir class setup skip. All six native Elixir CI platform/version combinations passed. The three dependency PRs #60–#62 are merged. Owner acceptance/issue closure and final release qualification remain distinct.

The directing user authorized removal of the two missing legacy worktrees. Their commit references and registration metadata were preserved before Git pruned the two stale registrations. This resolves those two inventory blockers; active peer worktrees remain owned by their contributors.

The refreshed tracker contains 24 open issues and draft PR #68. Newly included issue #22, issue #67, issue #69 and issue #70 retain their acceptance contracts. #22 remains RETAINED-PROJECT-001; the active FreeBSD review owns #67 and its #69/#70 dependencies. Do not duplicate or infer completion from the draft review's earlier native or baseline evidence.

The next independent implementation is PYTHON-TARGET-001 (#65). Its locked Python wheel profile opts into an explicit source projection, preserving original source and full marked requirements. The selected target controls active root dependencies; only reviewed, exact-hash backend files are omitted from the derived build tree. Missing active imports, target/source drift and changed sealed artifacts still refuse. Thirteen focused projection tests, twelve existing Python regressions and four dependency lifecycle regressions pass locally. Full local, installed and native/hosted qualification remain required before landing.

Receipt repair checkpoint

PR #71 landed the target-specific Python source projection. PR #72 repaired generation case naming, bounded missing-module retries and the current project receipt; it also addressed the Windows cold-start probe timeout seen after #71. Main commit 450d2a3f99e5e862458ce6cdd604eb77f72ff184 passed all 26 jobs in the exact post-merge CI run. The parallel checkpoint runner for #56 is the next implementation under qualification. This records development progress, not release readiness or publication authority.