Skip to content

Anuva Development Policy Phase 2 Implementation Plan

Status

Status: complete on 2026-07-29. Gate 1 implementation, Gate 2 live installation, and Gate 3 review and merge all passed. PR #23 merged to main at commit 9c1fe7ef9ebf2c6ce65dc89844c46285a725ca6a.

Phase 1 was merged through PR #22 on 2026-07-29 at merge commit d67cd8851c279301d2d054ae412c8af470da0324.

The initial approval authorized the listed Product Main implementation, isolated tests, and a focused draft pull request. It did not by itself authorize a live CLI replacement, machine-tool installation or upgrade, or a merge. The live installation and merge were later approved through their separate gates and are recorded below. Phase 2 created no Linear issue because the approved development-process lane does not require one.

The implementation branch has completed the source test gate, including compiled-artifact identity, isolated installation, idempotence, dirty-build rejection, post-switch recovery, checksum rejection, rollback, inverse rollback, fixed toolchain adapters, and packaged skill validation without Python.

Approved first-install rollback amendment

On 2026-07-29, the user approved the focused amendment required by the Gate 1 preview: when a first packaged installation finds the valid Phase 1 source-backed launcher, it must preserve that launcher as the closed legacy-source target before replacing the stable launcher. The installer records previous=legacy-source, and the normal guarded rollback command can then switch from the first packaged build to the preserved source launcher and back again.

This amendment authorizes only the existing Phase 2 Product Main paths, isolated tests, durable documentation, and an update to draft PR #23. It adds no dependency, arbitrary path input, live installation, toolchain mutation, sibling-repository write, Linear mutation, shared-skill removal, or merge authorization.

Gate 2 live installation and rollback evidence

The user approved the exact Gate 2 machine effects on 2026-07-29. Product Main then installed only the reviewed clean artifact:

  • build: 0.2.0-gc8776c067168;
  • source commit: c8776c0671682e9d1d4539337bf11a8c8df0f141;
  • executable bytes: 102302208;
  • executable SHA-256: a823d877d710ed23cbc9ed0b22a25e2df8537dad0354f2ac05e2373b6a1256e0;
  • install receipt: 20260729T154852Z-cli-install-bd2d;
  • installed executable: %LOCALAPPDATA%\Anuva\cli\versions\0.2.0-gc8776c067168\anuva.exe;
  • final current: 0.2.0-gc8776c067168; and
  • final previous: legacy-source.

The installer preserved the Phase 1 launcher byte-for-byte at the fixed legacy location. Its manifest and actual SHA-256 both equal a991057c20825e7ab6934945193933aa9dfc06ed770833e831d8421cca9f90c3. The stable launcher contains no Product Main path and resolves through the real Windows user PATH.

The managed sandbox's reduced registry view initially omitted the launcher directory. The keyring-capable user context proved that the real user PATH already contained %LOCALAPPDATA%\Anuva\bin; therefore the installer correctly reported pathUpdated=false and restartRequired=false and made no duplicate PATH entry.

The guarded rollback dry-run proved the packaged-to-legacy transition with both checksums. Confirmed receipt 20260729T155049Z-cli-rollback-a4bb activated legacy-source; anuva --version then reported 0.0.0-development (source development) and cli status remained healthy. The inverse dry-run proved the exact return transition, and confirmed receipt 20260729T155259Z-cli-rollback-fec2 restored the reviewed packaged build.

Final read-only acceptance through the PATH-resolved stable launcher passed from all configured working directories:

Repository Public docs URL Active identity
anuva-main-video-creator https://main1.girishd.com/ 0.2.0-gc8776c067168
anuva-bento https://bento1.girishd.com/ 0.2.0-gc8776c067168
anuvax-cms https://web1.girishd.com/ 0.2.0-gc8776c067168
anuva-python-server https://python1.girishd.com/ 0.2.0-gc8776c067168
anuva-unity-video-creator https://unity1.girishd.com/ 0.2.0-gc8776c067168

Every repository reported a healthy packaged runtime at the installed executable, preserved previous=legacy-source, and rejected the unknown option with exit code 2. Toolchain doctor reported all eleven fixed requirements satisfied, snapshot manifest version 1, and a bootstrap dry-run with no actions. Packaged skill validation passed for marketplace source, cached plugin 0.1.0, and all eight checked-in compatibility skills. No toolchain bootstrap, plugin mutation, shared-skill removal, sibling-repository write, Linear mutation, readiness transition, or merge occurred.

Gate 3 review and merge evidence

The user separately approved Gate 3 on 2026-07-29. The acceptance review found no blocking issue:

  • reviewed head: db7b8f662d54d6ca0f371dee618f5d34fa7ada39;
  • PR scope: 36 approved Product Main files, 3,585 additions, and 77 deletions;
  • reviews, comments, and unresolved review threads: none;
  • GitHub checks: none reported and no failed check;
  • mergeability: mergeable with the exact reviewed head;
  • guarded readiness receipt: 20260729T163139Z-pr-ready-1b06; and
  • merge method: repository-supported merge commit.

PR #23 merged at 2026-07-29T16:32:20Z as 9c1fe7ef9ebf2c6ce65dc89844c46285a725ca6a. Remote main contains the exact reviewed head, and the installed CLI remained healthy afterward with current=0.2.0-gc8776c067168, previous=legacy-source, and a zero-action toolchain dry-run. No Phase 3 implementation, Linear mutation, shared-skill removal, or sibling-repository write occurred.

Outcome

Phase 2 replaced the source-backed anuva.cmd runtime with an installed, versioned Windows executable and added a fixed, inspectable toolchain contract. The installed CLI runs from every configured Anuva repository without loading Product Main TypeScript source.

Completion evidence covers all of the following:

  • anuva --version reports semantic version 0.2.0, the full source commit, and whether the artifact was built from a dirty tree;
  • anuva doctor --json reports the executable path, build identity, active installation identity, and whether the running executable is the active artifact;
  • installation and upgrade preserve the prior artifact and switch one atomic active-version pointer only after checksum and smoke validation;
  • rollback works without rebuilding the old artifact;
  • toolchain diagnosis, snapshot, and bootstrap use one bundled, fixed manifest and accept no package, URL, script, executable, or repository input;
  • plugin and skill validation uses the CLI's bundled JavaScript yaml dependency and never installs a temporary Python dependency; and
  • representative read-only and fail-closed guarded commands pass from all five configured repositories with the installed executable.

Scope boundary

Included

  • Product Main CLI build identity and Windows x64 compiled packaging.
  • A narrow Product Main build script and replacement of the existing installer.
  • Side-by-side user-scoped installation, atomic activation, and one-step rollback.
  • CLI installation status and rollback commands.
  • A fixed Product Main-owned machine-toolchain manifest.
  • Read-only toolchain doctor and snapshot commands.
  • A guarded fixed-manifest toolchain bootstrap command.
  • Packaged plugin and skill validation.
  • A typed cachebuster replacement for the missing plugin-creator helper.
  • Product Main unit, integration, packaging, failure-recovery, and source-independence tests.
  • Product Main engineering, environment, policy-rollout, and CLI documentation.
  • Read-only acceptance execution from sibling repository working directories.

Excluded

  • Linear issues or mutations.
  • Changes to Bento, CMS, Python, Unity, or Dev Docs files.
  • Product implementation code.
  • GitHub Releases, release publishing, binary commits, or a new GitHub Actions workflow.
  • Codex rules or permission-profile changes.
  • MkDocs preview, verification, listener, index, tunnel, or publication behavior; those remain Phase 3.
  • Shared workflow-skill redesign or migration; that remains Phase 4.
  • Cross-repository installation or removal of checked-in shared skills; that remains Phase 5 and later compatibility gates.
  • Arbitrary package installation, arbitrary shell execution, YAML workflow execution, remote script download, automatic elevation, or unattended machine mutation.

Current implementation constraints

The implementation must preserve these observed contracts:

  • scripts/install-anuva-cli.ps1 currently writes %LOCALAPPDATA%\Anuva\bin\anuva.cmd, preserves the caller's working directory through ANUVA_INVOCATION_CWD, forwards arguments, and updates the user PATH idempotently.
  • src/cli.ts currently declares version 0.1.0 separately from package.json; Phase 2 will make package.json the semantic-version source.
  • Runtime configuration and mutable state remain under the existing %APPDATA%\Anuva and %LOCALAPPDATA%\Anuva roots.
  • Mutations continue to use typed confirmation, scoped locks, redacted receipts, path containment, and the executable allowlist.
  • The packaged executable may read configured repositories as task data. It must not import, launch, or otherwise depend on Product Main source files at runtime.
  • Existing checked-in .agents/skills/anuva copies and the Phase 1 plugin remain in place.

Packaged CLI contract

Build

package.json advances from 0.1.0 to 0.2.0 and becomes the only authored CLI semantic-version field. bun run build:cli will call a typed Bun build script that:

  1. reads and validates the package version;
  2. obtains the full source commit from git rev-parse HEAD;
  3. records whether tracked or untracked source inputs are dirty;
  4. invokes bun build --compile for the current Windows x64 runtime;
  5. disables runtime autoload of dotenv, bunfig.toml, tsconfig.json, and package.json;
  6. inlines only ANUVA_BUILD_VERSION, ANUVA_BUILD_COMMIT, and ANUVA_BUILD_DIRTY;
  7. writes the executable to ignored dist/anuva-cli/<build-id>/anuva.exe;
  8. writes a schema-versioned artifact.json containing name, version, commit, dirty state, platform, architecture, executable name, byte size, and SHA-256; and
  9. fails if the compiled executable's --version output does not match the manifest.

The build identifier is <version>-g<first-12-commit-characters> with -dirty appended for a dirty build. Dirty builds may be exercised in temporary tests but the live installer will reject them.

No generated executable, build directory, or machine receipt is committed.

Installation layout

The default user-scoped layout is:

%LOCALAPPDATA%\Anuva\
  bin\
    anuva.cmd
  cli\
    current
    previous
    legacy-source\
      anuva.cmd
      target.json
    versions\
      <build-id>\
        anuva.exe
        artifact.json
  state\
    locks\
      cli-install.lock
  logs\
    receipts.jsonl

current and previous are single-line target identifiers, not paths or command text. A target is either a validated build identifier or the one literal legacy-source. The stable anuva.cmd reads current, composes the executable path under the fixed versions directory for a packaged target, or dispatches the fixed cli\legacy-source\anuva.cmd path for the legacy target. It preserves ANUVA_INVOCATION_CWD, forwards all arguments, returns the target's exit code, and contains no Product Main path itself.

legacy-source\target.json is a closed manifest containing schema version, literal target kind, literal launcher filename, SHA-256, and the exact source development --version output. The preserved launcher may contain the historical Product Main path because it is the explicit rollback target; no caller can provide or alter that path through an installer or rollback option.

The installer adds -InstallRoot for isolated tests. It retains -TargetDirectory as a compatibility alias for the existing bin-directory contract, derives the installation root from that directory's parent, and rejects a compatibility value whose final directory is not bin. The production default remains %LOCALAPPDATA%\Anuva.

Atomic install and upgrade

The replacement scripts/install-anuva-cli.ps1 is a narrow packaging helper explicitly allowed by this plan. It accepts one artifact directory produced by bun run build:cli; it does not accept a URL, package name, executable command, or install procedure.

Under an exclusive cli-install.lock, it will:

  1. resolve the artifact directory and reject path traversal, missing files, unknown manifest fields, non-Windows or non-x64 artifacts, dirty artifacts, and unsupported versions;
  2. recompute and compare the executable SHA-256 before execution;
  3. run only the staged executable with --version and compare its output with artifact.json;
  4. copy into a unique staging directory below the installation root;
  5. recompute the staged checksum and smoke-test the staged executable;
  6. atomically rename the staging directory to versions/<build-id>;
  7. on the first packaged installation, validate and smoke-test an existing Phase 1 source launcher, copy its exact bytes into a staged legacy-source target, write its closed checksum manifest, and atomically publish that target;
  8. write previous from the validated old current value, or write the literal legacy-source target for that first installation;
  9. atomically replace current through a same-directory temporary file;
  10. create or refresh the stable launcher without changing an already-correct user PATH; and
  11. write a redacted receipt with old target, new target, checksum, whether the legacy source was preserved, pointer transition, and recovery command.

An existing identical version is an idempotent success. A collision with different bytes fails closed. Any failure before the pointer replacement leaves the old version active. A failure after replacement restores the old pointer before returning a partial-failure receipt.

Installed CLI commands

Add:

anuva cli status --json
anuva cli rollback --dry-run
anuva cli rollback --confirm

cli status validates the launcher, current and previous target identifiers, packaged or legacy manifests, checksums, current executable or launcher path, and running target identity.

cli rollback accepts no target argument. It can switch only from the valid current target to the valid recorded previous target under the CLI install lock. For a packaged target it verifies the manifest, checksum, platform, architecture, and --version result. For legacy-source it verifies the closed target manifest, fixed launcher location, checksum, and exact source development --version result. Only then does it atomically swap current and previous. Missing, equal, escaping, unhealthy, or tampered pointers fail before mutation.

Rollback therefore remains available from an installed artifact without Product Main source for packaged-to-packaged transitions. The first-install bootstrap additionally retains the Phase 1 source launcher so rollback remains available while that Product Main checkout and Bun runtime remain present. Initial installation and upgrade remain explicit Product Main build-and-install operations.

Build identity and diagnostics

Add a BuildInfo contract with:

  • semantic version;
  • full source commit;
  • dirty flag;
  • build identifier;
  • runtime kind: source or packaged;
  • platform and architecture; and
  • process.execPath.

Source-mode tests receive an explicit development build identity; production code will not read package.json at runtime. Commander uses the same BuildInfo object for --version.

anuva doctor will add CLI build and installation checks before the existing tool, credential, repository, database, tunnel, and Unity checks. It will distinguish:

  • packaged and active;
  • packaged but not active;
  • source-backed compatibility mode;
  • missing installation metadata;
  • corrupt or mismatched manifest/checksum; and
  • an installation path inaccessible in the current sandbox.

Existing GitHub keyring guidance remains unchanged.

Fixed toolchain contract

Bundled manifest

Add config/toolchain.v1.json and import it statically so the packaged executable contains the reviewed manifest. Its schema allows only fixed tool keys, numeric dotted minimum and exclusive-maximum versions, required or optional status, a detection kind, and one enumerated installation kind.

It contains no raw command arrays, script text, environment expansion, working directory, free-form executable name, or URL. Each detection and installation kind maps to reviewed arguments in TypeScript.

The initial manifest is:

Tool Supported version Installation contract
Anuva CLI >=0.2.0 <0.3.0 Report installer recovery; never self-download
Git >=2.41.0 <3.0.0 WinGet Git.Git
GitHub CLI >=2.96.0 <3.0.0 WinGet GitHub.cli
Bun >=1.2.0 <2.0.0 WinGet Oven-sh.Bun
Node.js >=24.0.0 <25.0.0 WinGet OpenJS.NodeJS.LTS
pnpm >=10.0.0 <12.0.0 WinGet pnpm.pnpm
Shared Python >=3.12.0 <3.15.0 WinGet Python.Python.3.14
MkDocs >=1.6.0 <2.0.0 Fixed Python user packages from PyPI
Material for MkDocs >=9.0.0 <10.0.0 Fixed Python user packages from PyPI
Cloudflared >=2025.11.0 <2027.0.0 WinGet Cloudflare.cloudflared
Unity Editor configured path, optional Detection only; never installed

The fixed Python package list is mkdocs>=1.6,<2 and mkdocs-material>=9,<10. It uses the manifest-selected shared Python runtime and the default PyPI index; the CLI accepts no package or index override. Repository Python environments and repository package managers remain out of scope.

Command behavior

Add:

anuva toolchain doctor --json
anuva toolchain snapshot --json
anuva toolchain bootstrap --dry-run
anuva toolchain bootstrap --confirm

toolchain doctor returns one policy result per fixed manifest entry: satisfied, missing, inaccessible-in-sandbox, outdated, incompatible, or optional-missing. Detection records the resolved path, raw output, normalized version, and reason without exposing secrets.

toolchain snapshot returns the same exact detected versions and paths plus manifest version, machine name, packaged CLI build identity, and timestamp. It does not write a file or receipt.

toolchain bootstrap accepts no tool, package, URL, command, or path argument. Dry-run returns the ordered fixed actions needed for all noncompliant required entries and identifies actions that need elevation or a new terminal. Confirmation:

  • requires the existing mutation confirmation contract;
  • acquires one toolchain-bootstrap lock;
  • skips already-satisfied entries;
  • executes only the manifest key's compiled adapter;
  • never downloads or executes a remote script;
  • never elevates itself;
  • re-detects each tool after its action;
  • stops on the first failed or still-incompatible action;
  • records completed and remaining actions in a redacted receipt; and
  • returns exact manual recovery when WinGet, Python, the keyring, or administrative access is unavailable.

WinGet and Python execution are added only as internal fixed adapters. Their presence in the process executable allowlist does not create a generic CLI surface, and tests must prove user input cannot reach their argument lists.

The Anuva CLI entry is diagnosis-only for bootstrap. Live CLI installation continues through the reviewed artifact installer so the running executable never downloads or chooses its replacement.

Packaged plugin and skill validation

Add:

anuva skills validate --json
anuva skills cachebuster --label <label> --dry-run
anuva skills cachebuster --label <label> --confirm

skills validate has no path argument. It validates:

  • the fixed Product Main plugins/anuva-development source resolved from machine configuration;
  • .codex-plugin/plugin.json;
  • the Product Main marketplace entry;
  • every bundled SKILL.md frontmatter block;
  • every agents/openai.yaml;
  • name, semantic version, relative-path containment, required metadata, duplicate identity, placeholder, and skills-only constraints;
  • all checked-in compatibility skill paths; and
  • every discoverable cached anuva/anuva-development version under the current user's Codex plugin cache, reporting cache absence as not verified.

The command uses the already bundled yaml and zod dependencies. It performs no Python invocation, dependency installation, network request, or mutation.

skills cachebuster replaces the missing plugin-creator Python helper with a typed Product Main operation. The label must match ^[a-z0-9][a-z0-9.-]{0,47}$; the command updates only the fixed development plugin manifest version from <base> to <base>+<label>, preserves valid semantic versioning, validates the complete plugin before and after, uses an atomic file write and scoped lock, and writes a redacted receipt. Tests use an isolated fixture and never change the real Phase 1 plugin version.

No shared skill is removed or migrated in Phase 2.

Exact repository changes after approval

Packaging and runtime

  • package.json: set CLI version 0.2.0; add build:cli and check:packaged scripts.
  • src/cli.ts: use embedded build identity; add the cli, toolchain, and skills command families without changing existing command contracts.
  • src/core/build-info.ts: build identity and source-mode fallback.
  • src/core/atomic-file.ts: same-directory atomic text and JSON replacement.
  • src/core/config.ts: add deterministic CLI installation paths to RuntimePaths.
  • src/core/version.ts: normalize and compare the fixed numeric tool versions.
  • src/schemas/cli-artifact.ts: closed artifact-manifest and pointer schemas.
  • scripts/build-anuva-cli.ts: typed compile, metadata, checksum, and smoke validation.
  • scripts/install-anuva-cli.ps1: replace the source-backed launcher installer with the artifact transaction.
  • scripts/README.md: document why the build and initial-install helpers are the narrow packaging exception.

CLI installation, toolchain, and validation

  • src/commands/cli/index.ts: status and guarded rollback.
  • config/toolchain.v1.json: the fixed bundled manifest above.
  • src/schemas/toolchain.ts: closed manifest and result schemas.
  • src/adapters/toolchain.ts: fixed detection and installation adapters.
  • src/commands/toolchain/index.ts: doctor, snapshot, dry-run, and confirmed bootstrap orchestration.
  • src/commands/skills/index.ts: packaged validation and guarded cachebuster.
  • src/commands/doctor.ts: CLI build and installation identity checks.
  • src/adapters/process.ts: only the executable names required by the fixed toolchain adapters; no path execution or generic command surface.

Tests

  • tests/unit/build-info.test.ts
  • tests/unit/cli-artifact.test.ts
  • tests/unit/version.test.ts
  • tests/unit/toolchain.test.ts
  • tests/unit/skills-validation.test.ts
  • tests/integration/packaged-cli.test.ts
  • tests/integration/cli-install.test.ts
  • tests/integration/toolchain.test.ts
  • tests/integration/launcher.test.ts
  • tests/integration/cli.test.ts
  • tests/unit/doctor.test.ts
  • tests/unit/plugin-distribution.test.ts

Documentation

  • docs/development/DevelopmentProcessPolicy.md
  • docs/development/AnuvaDevelopmentPolicyImplementationPlan.md
  • docs/development/AnuvaDevelopmentPolicyPhase2ImplementationPlan.md
  • docs/development/DevelopmentEnvironment.md
  • docs/development/index.md
  • docs/engineering/AnuvaCli.md
  • docs/engineering/Skills.md
  • mkdocs.yml

No other path is authorized by approval of this plan. A necessary additional path or command is a plan revision and new approval, not an implementation detail.

Implementation sequence

  1. Create a new managed Phase 2 implementation branch from the then-current main; do not reuse this planning-only branch as implementation approval.
  2. Revalidate the Phase 1 merge, clean worktree, current package lock, installed plugin, active launcher, and current tool versions without mutation.
  3. Implement build identity, artifact schema, compile script, and package scripts.
  4. Implement the isolated installer transaction and stable launcher, preserving existing argument, working-directory, exit-code, and PATH behavior. On the first packaged installation, preserve a valid Phase 1 launcher as the checksum-manifested legacy-source rollback target.
  5. Implement CLI installation status and rollback for the closed union of packaged build identifiers and legacy-source.
  6. Implement and bundle the closed toolchain manifest, detection adapters, doctor, snapshot, and dry-run.
  7. Implement confirmed bootstrap against fake adapters first; keep live bootstrap unexecuted.
  8. Implement packaged skill validation and the guarded cachebuster replacement.
  9. Extend unit and integration tests, including failure injection, tampered artifacts, pointer recovery, process-argument capture, and rejected input.
  10. Update Product Main documentation while retaining Phase 3 and later compatibility requirements.
  11. Run source checks and the separate packaged acceptance suite.
  12. Commit and push a focused draft implementation PR.
  13. Present the exact clean artifact version, commit, checksum, current active build, proposed pointer transition, toolchain dry-run, and recovery.
  14. Pause for explicit authorization before changing the live launcher or confirming any toolchain bootstrap action.
  15. After live-install authorization, install only the reviewed clean artifact, verify from all five repository working directories, test rollback and re-upgrade, and record non-secret evidence.
  16. Return the draft PR, checks, documentation previews, installed build identity, toolchain state, and rollback evidence; pause for separate merge approval.

Verification matrix

Source and contract checks

  • bun run typecheck
  • bun test
  • git diff --check
  • existing command-help, confirmation, receipt, lock, path, redaction, repository, PR, docs, and process tests remain green;
  • no new dependency is needed for version comparison or YAML validation; and
  • bun.lock remains unchanged unless an approved implementation revision explicitly adds a dependency.

Artifact and installer

  • Two clean builds from the same commit have identical embedded identity; the manifest checksum matches each executable.
  • --version and doctor identity agree with artifact.json.
  • The compiled artifact runs after its build directory is copied into an isolated install root and the original copy is removed.
  • The stable launcher contains no Product Main path and preserves a caller path containing spaces.
  • Install and same-version reinstall are idempotent.
  • A first packaged installation preserves the Phase 1 launcher byte-for-byte, records its checksum in the closed legacy manifest, and records previous=legacy-source.
  • Rollback to legacy-source invokes the preserved source launcher with the original caller working directory, arguments, and exit code; inverse rollback returns to the reviewed packaged build.
  • Upgrade retains the old artifact and records previous.
  • Packaged-to-packaged rollback swaps only two validated build identifiers.
  • Re-upgrade returns to the reviewed build.
  • Bad schema, extra manifest fields, dirty builds, wrong platform or architecture, wrong checksum, escaping identifiers, version mismatch, staged smoke failure, and colliding bytes all leave the old pointer active.
  • An injected post-switch failure restores the old pointer and records partial recovery.

Toolchain

  • Every manifest entry parses and every key maps to one compiled adapter.
  • Missing, inaccessible, outdated, incompatible, optional-missing, and satisfied states have fixtures.
  • Version normalization covers the observed Git Windows suffix, v-prefixed Node output, year-based Cloudflared versions, and Python or MkDocs text.
  • Dry-run is deterministic and performs no process mutation.
  • Fake confirmed bootstrap executes only the exact ordered adapter arguments, skips satisfied tools, re-detects results, stops on failure, and redacts receipts.
  • Unknown keys, packages, URLs, commands, executables, paths, and manifest fields are rejected.
  • Live acceptance runs toolchain doctor, toolchain snapshot, and toolchain bootstrap --dry-run; it does not run --confirm without the separate machine-mutation approval.

Skills and plugin

  • Validate repository source, marketplace, all skill frontmatter, UI metadata, cached versions, and compatibility-skill retention.
  • Run validation from the packaged executable with Python unavailable.
  • Confirm no .validator-deps, pip install --target, or cache helper is created.
  • Cachebuster dry-run is stable; confirmed fixture mutation changes only the fixed plugin version and rollback through fixture restoration passes.
  • The real plugin remains installed and all checked-in shared skills remain.

Five-repository source-independence acceptance

From each configured repository working directory, using the installed artifact resolved by where.exe anuva, run:

anuva --version
anuva cli status --json
anuva context show --json
anuva docs links --repository current --file docs/index.md --json
anuva --definitely-unknown

Acceptance requires the same build identifier in every repository, the correct repository identity and docs URL, no Product Main TypeScript process or source launcher in the process tree, and exit code 2 for the unknown option.

Existing integration tests also prove that a mutating command without --dry-run or --confirm fails closed. Sibling repositories remain read-only throughout this acceptance.

Documentation

  • Record the required pre-edit timestamp and ensure the owned Product Main preview before each logical docs change.
  • Validate recursive indexes.
  • Run one fresh strict build and served-page comparison for every changed page.
  • Return every exact machine-specific preview URL.
  • Do not change Phase 3 preview semantics while documenting Phase 2.

Approval and stop conditions

Gate 1: implementation

Approval of this exact plan authorizes only the listed Product Main paths, temporary-root tests, a managed implementation branch, and a focused draft PR. It does not authorize a live CLI replacement, a confirmed tool installation or upgrade, or merge.

Gate 2: live machine mutation

Before live installation, present:

  • artifact version, full commit, dirty state, byte size, and SHA-256;
  • current and proposed installation paths;
  • current and previous target identifiers and target kinds;
  • preserved legacy-source launcher checksum when that bootstrap target exists;
  • exact pointer change;
  • whether user PATH changes;
  • complete toolchain dry-run actions;
  • commands requiring elevation or a new terminal; and
  • exact rollback command.

Only the user's explicit approval of those concrete effects authorizes the live installer or any confirmed bootstrap action. Toolchain approval may be narrower than the CLI install; unapproved actions remain dry-run only.

Gate 3: merge

After the draft PR, required tests, live artifact verification, rollback and re-upgrade evidence, and strict docs previews are complete, return the exact PR state and findings. Merge only on a separate explicit user request.

Gate 3 was separately approved and completed on 2026-07-29. PR #23 merged at 9c1fe7ef9ebf2c6ce65dc89844c46285a725ca6a; this approval did not authorize Phase 3.

Stop and revise this plan if implementation needs:

  • a new repository write;
  • a new dependency;
  • a remote artifact source or release mechanism;
  • a raw command, URL, package, or path input;
  • automatic elevation;
  • MkDocs, Codex rules, Cloudflare, or shared-skill migration changes;
  • removal of any compatibility skill; or
  • a different installation, version, or rollback contract.

Rollback

Planning rollback is deletion of this unmerged planning branch; it has no runtime effect.

Implementation rollback before live installation is normal Git reversion and removal of ignored temporary build output. After live installation:

  1. run anuva cli rollback --dry-run;
  2. inspect the exact current-to-previous target transition, including whether the destination is a packaged build or legacy-source;
  3. run anuva cli rollback --confirm only with authorization;
  4. verify anuva --version, anuva cli status --json, and representative read-only commands from all five repositories; and
  5. retain both artifact directories, the preserved legacy-source directory, and the redacted receipt until the Phase 2 PR is merged and the new build has remained healthy.

No rollback step deletes checked-in skills, plugin source, repository history, machine secrets, unrelated binaries, or sibling repository files.