The canonical specification describes current functionality, authority boundaries and workflow/module wiring. Its published book is built from the same committed chapters. Planned rollout features remain explicitly pending.
The consolidated maintenance plan and progress tracker records the cross-repository rollout, owners, acceptance gates and remaining work.
Verified first-party npm releases wake a self-hosted Renovate runner. It reads active workspace manifests on each allowlisted repository's default branch, checks stable npm versions and their first-party prerequisites, and opens dependency PRs. Compatible updates auto-merge after successful CI and existing repository merge rules. Publication, signing and deployment retain their separate gates.
The initial configuration is pilot / dry-run / schedule disabled. Creating the repository or merging its source does not enable dependency writes.
Use Node 24.15.0 and the pinned pnpm version:
pnpm install --frozen-lockfile --ignore-scripts
pnpm verify
pnpm spec:search --semantic "dependency availability and reconciliation"
pnpm exec spec-validator doctor
actionlint .github/workflows/*.yml
pnpm inventorypnpm verify includes canonical validation, the mdBook build and mapped
spec-first checks in addition to the existing source checks/tests. Local builds
require mdBook 0.5.4. CI installs that exact version; QMD search and model downloads
remain local discovery tools. Generated spec/book/ stays ignored. Pages deploys
only that book from verified main, with deployment permissions isolated from
the read-only build job.
GH_TOKEN is a read token for inventory discovery; public repositories can also
be read with the workflow's token. Inventory outputs live under ignored
reports/, including exact source revisions, owners, consumers, unpublished
references, and runtime strongly connected components. A registry error fails
the scan; only HTTP 404 means unpublished. The release notification is a hint,
never authority for a version bump.
Run pnpm maintenance:audit with a read-only GH_TOKEN to write
reports/maintenance-audit.json. The report includes source revisions,
workflow paths, known PR creator authentication and explicit coverage gaps.
It inspects direct gh PR commands and known creation actions; scripts and
reusable workflow internals still need review. Findings are recommendations,
not permission to write or proof that a PR can merge.
monitoring.repositories adds monitoring-only infrastructure;
monitoring.excludedRepositories takes precedence for this audit. Neither
changes the dependency update allowlist, active rollout settings or holds.
Maintenance UI adoption is tracked separately in S4 of the plan.
Read failures produce a partial report and a nonzero exit status.
The read-only Audit maintenance policy workflow runs daily and on manual
dispatch, retaining its JSON artifact for 14 days. It creates no PRs and uses
no App key. Findings do not fail the run; missing coverage does.
The manual Verify maintenance App readiness workflow probes one explicit
pilot (.github, Plugins or Notes) using the coordinator's existing encrypted
credentials. It requests only repository/PR read access, verifies the token is
restricted to that repository and reports readiness without changing targets.
Run it on main; no secret value must be retrieved or copied. Failure to mint a
token means installation/credential setup needs inspection. Successful reads do
not prove write readiness; that is established by the subsequent reviewed pilot.
Create a GitHub App owned by lapismd, named
lapismd-dependency-bot (or set LAPIS_DEPENDENCY_BOT_LOGIN in consumers).
Choose Any account (public registration), so the same App can be installed
on both lapismd and stevejuma/jj-store. A private organization-owned App can
only be installed on its owning organization. Public registration does not
expand this coordinator's explicit repository allowlist.
Disable webhooks. Grant repository contents and pull requests read/write, metadata read, and checks and commit statuses read. It needs no workflow write, administration, npm, signing, or deployment credentials.
Install it for the allowlisted LapisMD repositories, this coordinator, and
separately for stevejuma/jj-store. Installation tokens are minted per target
repository and automatically revoked by actions/create-github-app-token.
Configure the following organization values, restricting the private-key secret to this coordinator, the publisher workflows that notify it, and the Notebook and AI Controller version-PR workflows:
| Name | Kind | Value |
|---|---|---|
LAPIS_DEPENDENCY_APP_CLIENT_ID |
variable | App client ID |
LAPIS_DEPENDENCY_APP_PRIVATE_KEY |
secret | App-generated PEM key |
LAPIS_DEPENDENCY_BOT_GIT_AUTHOR |
coordinator variable | lapismd-dependency-bot[bot] <APP_USER_ID+lapismd-dependency-bot[bot]@users.noreply.github.com> |
LAPIS_DEPENDENCY_BOT_LOGIN |
coordinator/consumer variable, optional | Alternate installed App login |
For stevejuma/jj-store, configure the corresponding client-ID variable and
notification key secret in that repository too. No secrets belong in this tree.
- Merge consumer CI/versioning integrations and publisher notification jobs.
Enable
LAPIS_DEPENDENCY_VERSION_PR_ENABLED=truein Notebook and AI Controller after their new Changesets workflows pass review. Community remains held out of the allowlist until its CI integration PR #2 is approved and merged. These workflows use repository-scoped App tokens so generated PRs start functional CI automatically. They only prepare version PRs; existing publication gates remain separate. - Dispatch Reconcile first-party npm dependencies with all write variables unset. Inspect inventory and Renovate dry-run summaries for the four pilot repositories: Mira, Design Core, Notes and Plugins.
- Set coordinator variable
LAPIS_DEPENDENCY_WRITES=truefor the reviewed pilot. - Review the pilot PRs and their functional checks. Set
LAPIS_DEPENDENCY_PHASE=fullonly after the other repository integrations land. - Set
LAPIS_DEPENDENCY_SCHEDULE=trueto enable the hourly catch-up scan.
Unset LAPIS_DEPENDENCY_WRITES to return to dry-run; unset the schedule variable
to stop scheduled scans. Manual dispatch always supports diagnosis. Failed
notifications can be retried independently of publication; an hourly scan also
discovers manual publications and missed events.
Notifications use repository_dispatch / lapis-npm-published-v1 with
repository, a 40-character sourceSha, and packages: [{name, version}].
Source workflows call the pinned notify.yml only after their verification
job succeeds. Manually published packages without a release workflow are found
by reconciliation. The coordinator does not install or invoke an npm publisher. Notebook now has
its own protected release pipeline; its publication approvals remain separate.
Compatible updates refresh one rolling PR per repository and auto-merge through
Renovate on a later reconciliation after all reported checks succeed. Renovate
must observe an up-to-date branch; existing review and merge requirements still
apply. platformAutomerge: false and ignoreTests: false keep failed, pending,
cancelled, or missing checks from being bypassed by native auto-merge.
Each upstream family gets a separate draft PR with auto-merge explicitly
disabled for major or 0.x minor updates. Exact, caret and tilde styles remain
intact. Existing peer support is retained; widening is proposed
only when a new version falls outside that support. Runtime cycles use lockfile
updates for already-compatible ranges to avoid release loops.
The shared post-upgrade helper adds one deterministic Changeset for affected public runtime/peer contracts, or an empty Changeset where release-intent rules require it. Private application roots do not become publication targets. Repositories must complete Changesets onboarding before a runtime update can be written. Existing independently versioned plugin packages stay independent. Version preparation installs the pinned Deno runtime required by Changesets 3 before invoking the CLI. This is separate from the Node-only specification validator and does not enable a consumer service.
Trusted dependency-bot PRs and existing generated version PRs skip specification checks. The policy uses the PR author, not the person rerunning a job. Audits, types, unit tests, builds, packaging, interactions, accessibility and existing release gates remain active. The copied policy module is maintained here and uses the installed validator API to retain functional lanes embedded in its aggregate check command. Docker workers receive only its explicit public PR-context variables, never credentials.
Existing lockfile CI-image workflows refresh digest pins after merge. Dependency PRs install their exact candidate lockfile; a previous image digest is never relabelled as a build of the new dependency graph. Rust, Git revisions, container versions, and third-party dependency automation are not managed here.
lapis-plugin-docs is included in the full rollout with the other standalone plugins. Deprecated terminal-host stays excluded.
The terminal-host npm package is also ignored in remaining manifests, so stale
Deno development declarations cannot keep that legacy release chain alive.
Parked Deno desktop and server workspaces are excluded by workspace discovery.
AI Host remains included because the current Tauri application consumes its
portable file-tools leaf through Notes API. AI Controller also supplies portable
client and memory exports to the active AI plugin; no Deno service is enabled by
this automation.
Community remains temporarily excluded by operator decision. Restore its
phase: "full" allowlist entry only after
its integration PR lands; do
not enable its new version-PR workflow while that integration is held.
Desktop remains in ownership/consumer discovery with an explicit write hold.
Its private Profile/API 0.2.3 cohort stays pinned. Its unpublished @lapismd/ai
dependency and CI archive projection require qualified Renovate support before
the hold is removed. Inventory also holds any consumer with an unpublished
first-party registry dependency, rather than proposing an un-installable PR.
profile-refresh.yml runs hourly when LAPIS_PROFILE_REFRESH_ENABLED=true,
with manual dispatch for recovery. It runs .github's
own npm-status generator without credentials, then validates and publishes the
README using a separate coordinator worker and an App token scoped to .github.
No private key is copied to the source repository. The old source writer is
retired and App-created CI/no-change acceptance is recorded in
the rollout tracker.
Stale source or concurrent branch edits fail closed; regenerate after inspecting
the current main and rolling PR. Manual repair commits stop automated updates.
If a write outcome is uncertain, inspect automation/npm-status-refresh and its
open PR before retrying. The worker will not overwrite an orphaned branch or
retry an uncertain write. Ordinary checks and merge policy remain in force.
S3 admission is available behind the default-off LAPIS_DEPENDENCY_WAVES gate.
It derives package/path release chains, constrains the actual reconciliation
matrix and versions, preserves scoped repair branches and reconciles durable
operation identities. State writes have a separate default-off gate and remain
on a dedicated public-safe coordinator branch. See the pilot, recovery and
rollback runbook before any activation. Hosted release-chain
acceptance remains pending; merging source does not activate either gate.
The upstream version template uses the reviewed Node-only Changesets contract and validates it before App minting. Existing CLI majors and source-owned recipes remain intact. Production candidate preparation rejects newly unqualified runtime bytes and incompatible cohort changes before release intent; inventory reports source-bound cohort observations and missing coverage. See the S6 tooling rollout and remaining gates. Consumer adoption, central operational drift coverage and exact advisory policy are still required; this foundation does not complete S6 or enable writes.