ALDC plugins and recoverable installation¶

ALDC distributes the same role and workflow contracts through host-specific adapters.

Consumer commands¶

Use Node 20+ from a checkout or local npm archive. Commands write only to the chosen project; use separate disposable projects for host acceptance.

Chat retains BC28 as default and the recorded profile on update. A profile switch requires --force. Custom target directories must be inside the project and must not cross symlinks. Terminal initialization does not change the Chat profile. No initializer runs dependency installation. Install the Chat validator's js-yaml separately with npm install in its installed tools/aldc-validate directory when needed. Node runs all installation adapters; Context Doctor separately requires Python 3.9+.

Tracked, unedited toolkit files update automatically. Unknown or customized files remain visible collisions. --force authorizes their replacement with backup. Chat preserves its historical successful exit on skipped collisions; inspect its output and verify-install. Terminal initializers return exit 2 for collisions. Receipts retain unresolved collisions; a repeated run cannot certify them as clean. Existing memory is always preserved. App/Test manifests, AL sources, editor settings and external host configuration are outside the installation plan.

Applying unreleased changes to an existing project¶

A checkout's package.json version is not evidence that its local changes are in the published npm package, VSIX or plugin cache. Changes listed as Unreleased need a new published version for normal versioned updates. Until then, use the updated checkout's installer/initializer commands above, previewing the exact existing project before applying. Use the project's current target directory and Chat profile; do not switch profiles merely to refresh contracts.

Plugin updates refresh the installed plugin payload, not arbitrary project copies:

• Claude Code: plugin agents and its bundled design guide follow the refreshed plugin. Project .claude/agents mirrors need their own update and can shadow plugin roles; do not add a second mirror to a plugin-based project. Re-run the updated plugin's scripts/init.js for its managed project rules/guidance when those change. That initializer does not install project agent mirrors.
• Codex plugin discovery: refresh the source/cache and restart the host, then verify the loaded ALDC skill. A marketplace entry can point at the updated local plugin directory. This does not rewrite project .codex/agents profiles.
• Codex local bootstrap: preview and apply the updated checkout's plugins/aldc-codex/scripts/init.js --project <project>, then use --verify and restart Codex. This updates tracked .agents/skills/aldc and .codex/agents copies. Use either plugin discovery or local bootstrap in a project.
• Copilot Chat: run the updated checkout's scripts/install.js install --yes --dry-run from the existing project root, then repeat without --dry-run and run verify-install. Updating another host's plugin does not refresh .github.

Review collisions before using --force; it replaces customized content with a recoverable backup. Keep the receipts and verify the actual sources loaded by a new host session. For Claude cache/version behavior see the manifest reference; for Codex local cache refresh see the plugin packaging guide.

Terminal guidance uses an ALDC managed block. Surrounding user text is preserved. Codex/CLI choose an existing AGENTS.override.md over AGENTS.md. If an override is introduced later, the old AGENTS.md remains intact. A locally changed managed block is a collision. Updating surrounding text may conservatively require review when the managed block also needs updating.

Recovery and provenance¶

The common transaction engine preflights all destinations, saves file preimages and modes, records a pending journal, then applies writes. Detected write failures restore the preceding files and receipt. A live/unknown operation lock is never stolen; a dead local process lock can be recovered. After interruption, run the matching surface's rollback before another installation.

Backups and receipts live in .aldc-install/ with a local ignore rule. Keep them until recovery is no longer needed. Rollback validates all preimages and current hashes before writing; later edits block restoration rather than being lost. Changed project memory is preserved even when rolling back a fresh installation. Rollback restores file content/modes, not arbitrary external effects or directory timestamps; it can leave empty directories. It does not undo user work performed since installation. The installer lock excludes other installers, not editors; stop concurrent edits during install/recovery. This is not a power-loss durability or adversarial filesystem guarantee.

Each terminal package has provenance.json with source and output SHA-256 digests. The complete source set records generator dependencies; output hashes verify the actual packaged payload before initialization. Hashes normalize LF/CRLF only; other modifications fail. This is drift/integrity evidence, not a publisher signature. Provenance detects accidental drift; it is not tamper-proofing. The lock is unsigned, so whoever can write to an installation can rewrite the lock with it. Derived build artifacts a run leaves behind, such as __pycache__, are excluded from both the source set and the payload listing for that reason: they appear in a correct installation. Regenerate one distribution with its sync:claude, sync:copilot-cli or sync:codex command. npm run sync:plugins explicitly rebuilds all three, without updating the development mirror or VSIX foundation. See surface generation. Validation checks drift and exercises initialization from the extracted archive.

Host scope and acceptance¶

Use either Codex plugin skill discovery or local bootstrap, never both in the same project. Plugin discovery alone does not install project TOML profiles. Domain skills are GUIDE.md references inside one discoverable ALDC skill to avoid duplicate registrations. The full Conductor remains present; independent review still needs actual delegation. Missing delegation cannot be replaced by a claim of independent self-review. No model, approval, sandbox or MCP override is installed.

Codex profile format follows official custom-agent documentation. Guidance precedence follows AGENTS.md discovery. The skill layout follows local skill discovery.

Compatibility¶

Confirm agent discovery and complete instruction loading in the installed host. Host versions, available tools and authentication determine which operations can run. A manifest or successful installation does not certify runtime execution. ALDC inherits host model, permission and MCP settings. See native AL tools for Copilot Chat and the packaged terminal guide for CLI hosts.