Skip to content

Anuva Development Policy Phase 3 Implementation Plan

Status

Status: complete. Gate 1 implementation, Gate 2 live acceptance, and Gate 3 review and merge passed on 2026-07-29. Corrected clean packaged artifact 0.2.1-g3dd30bca40f1 is active on machine one and passes source, packaged, rollback, five-repository, and authenticated HTTPS verification. PR #25 merged to main at commit a02084cc9628973f5a965512a48486ba51c979eb. The active Product Main guidance selects docs preview and docs verify.

Phase 2 is complete. PR #23 merged the packaged CLI and toolchain work, and PR #24 reconciled its durable completion status.

The user's Phase 3 planning, Gate 1, Gate 2, and Gate 3 approvals authorized the Product Main branch, implementation, exact live upgrade, rollback proof, read-only five-repository acceptance, readiness, and merge through their separate gates. They did not authorize a Cloudflare mutation or Phase 4. This phase created no Linear issue under the approved development-process lane.

Gate 1 implementation evidence

The source implementation now:

  • exposes timestamp-free docs preview and docs verify commands while retaining ensure, wait, validate-indexes, and links;
  • treats only process/configuration state as primary preview restart reasons and retains source, branch, and HEAD as diagnostics;
  • validates navigation, local links, orphans, user-facing sections, and meaningful indexes with the existing YAML dependency;
  • permits an external listener only for a single successful strict verification and never adopts or terminates it;
  • normalizes the nondeterministic default-theme MkDocs build timestamp before strict comparison;
  • preserves process-state schema version 1; and
  • sets the source package version to 0.2.1.

bun run check passes 109 tests. New temporary-repository integration coverage proves owned reuse across content, HEAD, and branch changes; configuration restart; stopped start; dead-registry recovery; external refusal and exact verification; and port-conflict classification. The compiled executable also starts and strictly verifies an isolated MkDocs repository without loading Product Main TypeScript source. The Product Main implementation also reuses owned live-preview PID 26904 across documentation evidence edits; installed strict verification passes without a restart or timestamp. Before Gate 2, no live installer, sibling preview, Cloudflare mutation, Linear mutation, shared-skill removal, or sibling write had occurred.

Gate 2 acceptance evidence

The first approved clean artifact, 0.2.1-g5c468136c28f, installed with the expected pointer transition and passed rollback and inverse rollback. Live read-only verification then exposed that the structure validator ignored MkDocs exclude_docs, collected link errors from unreachable pages, parsed nested-parenthesis links incorrectly, and classified structural index.md pages as orphans. Acceptance stopped before browser checks, the artifact was rolled back to 0.2.0-gc8776c067168, and no sibling file changed.

Product Main commit 3dd30bca40f1f1269b6431b05250c9902f5da520 corrected those compatibility defects and added deterministic regression coverage. The separately previewed and approved replacement artifact is:

  • build ID: 0.2.1-g3dd30bca40f1;
  • size: 102319616 bytes;
  • SHA-256: d8c08ecc4ec3c5a5e4c71a95b7588955551b6e9c9194640b68d6d14c0b5e550c;
  • platform and architecture: win32/x64;
  • source verification: 109 tests passed;
  • packaged verification: 7 tests and 117 expectations passed; and
  • real-user-context toolchain dry-run: healthy, manifest version 1, zero actions.

The exact replacement installed with no PATH change. Rollback selected 0.2.0-gc8776c067168; its legacy docs ensure and docs wait commands remained available. Inverse rollback restored the final healthy state:

current=0.2.1-g3dd30bca40f1
previous=0.2.0-gc8776c067168

The checksum-manifested legacy-source directory remains installed. All five preview commands reused healthy CLI-owned listeners:

Repository PID HTTPS route
Product Main 26904 https://main1.girishd.com/
Bento 18472 https://bento1.girishd.com/
Web 27184 https://web1.girishd.com/
Python 24900 https://python1.girishd.com/
Unity 15336 https://unity1.girishd.com/

The installed artifact performed one successful strict build, structure validation, and served-page comparison for docs/index.md in each repository. An authenticated browser opened every exact HTTPS route and observed the expected site title and root heading rather than Cloudflare Access. No sibling file or Git state, tunnel, route, DNS, certificate, Access policy, token, PATH entry, or machine tool changed.

PR #25 contained only the approved Product Main implementation.

Gate 3 review and merge evidence

The user separately approved Gate 3. The acceptance review found no blocking issue:

  • reviewed head: 916b85ae6aa6d1072e3780185cf2605c55b4ac2d;
  • PR scope: 19 approved Product Main files, 1,579 additions, and 87 deletions;
  • reviews, comments, and unresolved review threads: none;
  • GitHub checks: none reported and no failed check;
  • mergeability: mergeable with the exact reviewed head; and
  • merge method: repository-supported merge commit.

PR #25 merged at 2026-07-29T18:35:52Z as a02084cc9628973f5a965512a48486ba51c979eb. Local main fast-forwarded to the merge commit, and the local and remote managed Phase 3 branches were deleted. The installed CLI remained healthy with current=0.2.1-g3dd30bca40f1 and previous=0.2.0-gc8776c067168. All five preview states remained owned-healthy; Product Main strictly verified this merged record from main. No Phase 4 work, Linear mutation, shared-skill removal, sibling write, or Cloudflare mutation occurred.

Outcome

Phase 3 separates convenient working-tree preview from strict delivery verification:

  • anuva docs preview starts or health-checks one owned MkDocs process, relies on MkDocs live reload, and returns exact review URLs without a timestamp or strict build;
  • anuva docs verify runs one strict build for a logical update, validates documentation structure, and optionally compares requested served pages without requiring a process restart or pre-edit timestamp;
  • Markdown, branch, and Git HEAD changes no longer make the primary preview process stale;
  • configuration, executable, arguments, port, working directory, health, and process identity remain restart or refusal reasons;
  • external processes are never terminated or adopted as owned;
  • docs ensure, docs wait, and recursive index behavior remain available as explicit compatibility and rollback paths; and
  • all five machine-specific documentation routes passed read-only acceptance without changing sibling repository files or Cloudflare configuration.

The CLI remains an allowlisted executor. Phase 3 does not add a generic server, command, path, package, URL, route, or process-kill interface.

Baseline

The installed CLI is clean build 0.2.0-gc8776c067168. Product Main main is at Phase 2 completion merge 1fa610a1685af36a6556cc3d276b2f133bdec20e before this planning branch.

The current implementation couples preview lifetime to content generation:

  • src/commands/docs/index.ts hashes mkdocs.yml, every file under docs_dir, the Git branch, and Git HEAD;
  • any difference makes docs ensure stop and restart an otherwise healthy owned server;
  • docs wait requires --since, requires an owned current-generation process, runs a fresh strict build, and compares every requested served page;
  • validate-indexes requires a non-empty index.md in every directory; and
  • docs links already derives exact public URLs without requiring a running preview.

The planning baseline reproduced the coupling: switching from merged main to the Phase 3 planning branch changed Product Main from owned-healthy to owned-stale solely because of git-branch-changed. The other four configured repositories had dead registry records and no listeners. Phase 3 must handle those states without trusting or terminating an unowned process.

Fixed command contracts

anuva docs preview

The new primary preview command is:

anuva docs preview --repository <key|current> --file <paths...>

--file requires one or more Markdown paths contained by the selected repository's docs_dir. The command:

  1. resolves only a configured repository;
  2. validates and maps every path to its configured local and public URL;
  3. acquires the existing repository-scoped docs lock;
  4. classifies the registry, listener, health, process identity, command fingerprint, and MkDocs configuration state;
  5. reuses a healthy matching owned process even when docs source, branch, or HEAD changed;
  6. restarts only an identity-verified owned process whose command, configuration, working directory, port, or health requires replacement;
  7. removes a dead stale registry record before starting a replacement when the configured port is free;
  8. refuses an external or conflicting listener with its exact PID and state;
  9. starts MkDocs on 127.0.0.1 when stopped;
  10. health-checks the requested pages; and
  11. returns process state plus exact local and HTTPS URLs.

Starting or health-checking this reversible owned preview is approval-free under the development-process policy. docs preview therefore has no --confirm flag. It never starts Cloudflare Tunnel and never proves delivery correctness; strict proof belongs to docs verify.

Preview mode will not run a strict or non-strict static build. It will not use an external listener because content identity cannot be established without a build comparison.

anuva docs verify

The new verification command is:

anuva docs verify --repository <key|current> --file <paths...>

--file requires one or more contained Markdown paths. The command is read-only with respect to repositories and processes. It:

  1. validates the documentation structure described below;
  2. runs exactly one mkdocs build --strict into a temporary directory;
  3. maps all requested source pages to that one strict build;
  4. checks the configured local listener;
  5. compares every requested served page with the corresponding strict output, ignoring only the existing live-reload and canonical-URL differences;
  6. rejects raw local .md hrefs in rendered HTML;
  7. accepts an owned listener when its OS identity and configured listener PID match;
  8. accepts an external healthy listener for this invocation only when every requested page matches the strict output, thereby establishing content identity without adopting ownership; and
  9. returns strict-build, structure, listener-kind, page-hash, status, and exact URL evidence.

There is no --since input and no branch, HEAD, docs-hash, start-time, or process-restart prerequisite. A stopped, unhealthy, stale, or conflicting listener fails served-page comparison with an exact recovery message; users may still obtain URLs while stopped through docs links.

Compatibility commands

Phase 3 will not remove or silently reinterpret the old safety path:

  • anuva docs ensure --repository ... --confirm retains the Phase 2 current-generation restart contract;
  • anuva docs wait --repository ... --file ... --since ... retains the Phase 2 timestamp and owned-generation comparison;
  • anuva docs validate-indexes --repository ... retains recursive-index validation; and
  • anuva docs links remains process-independent.

The Product Main skill and instructions will select preview and verify after Phase 3 acceptance. The compatibility commands remain callable for rollback and for repositories not yet migrated. Their removal, if ever approved, belongs to the later shared-skill and repository-migration phases.

Process-state model

Process-state schema version 1 remains readable by CLI 0.2.0; Phase 3 will not add a schema migration that prevents CLI rollback.

The process record continues to contain:

  • executable, arguments, working directory, port, fingerprint, PID, OS identity, launcher identity, log path, and start time;
  • configHash as the configuration generation that can require restart; and
  • docs-source hash, branch, and HEAD as optional diagnostics only.

Primary preview staleness is limited to:

  • executable or argument mismatch;
  • working-directory, port, or mkdocs.yml content mismatch;
  • unhealthy owned process;
  • dead or reused PID;
  • listener PID not matching the trusted owned record; or
  • an unowned port occupant.

docs status will preserve existing fields and add an explicit classification without treating content diagnostics as restart reasons:

State Meaning Preview behavior
owned-healthy Trusted listener, desired process/configuration, healthy Reuse
owned-config-stale Trusted process but command, directory, port, or configuration changed Stop after identity verification and restart
owned-unhealthy Trusted listener is not healthy Stop after identity verification and restart
stale-registry Dead, reused, or listener-mismatched registry identity Remove dead record; refuse a live untrusted PID
external-listener Healthy listener without trusted ownership Refuse preview; permit verify only after exact page comparison
port-conflict Bound/listening PID does not provide the expected healthy site Refuse and report PID
stopped No record, listener, or port owner Start

No classification permits terminating an unowned process.

Documentation-structure verification

docs verify replaces recursive directory ceremony with meaningful checks. It will use the existing YAML dependency and add no package.

The new validator will:

  • require the root docs/index.md;
  • recursively resolve every mkdocs.yml navigation target within docs_dir;
  • reject missing, duplicate, escaping, absolute, and non-Markdown navigation targets;
  • walk local Markdown links from navigated pages and reject missing or escaping local targets;
  • report Markdown pages that are neither in navigation nor reachable from a navigated page;
  • reject navigation groups with no valid page descendant; and
  • report a user-facing directory only when it has neither a meaningful index.md nor an explicit navigation entry.

Directories containing only assets, generated output, archives, or organizational nesting do not need boilerplate indexes. They remain subject to path containment and any link or navigation target that references them.

The output is deterministic and sorted:

missingNavigationTargets
duplicateNavigationTargets
brokenLocalLinks
orphanedPages
emptyUserFacingSections
missingUserFacingIndexes

An empty set in every category is required. The legacy validate-indexes command remains unchanged as the rollback check during Phase 3.

Exact Product Main implementation scope

Implementation approval will authorize only these Product Main path classes:

CLI source

  • package.json: bump the packaged CLI from 0.2.0 to 0.2.1; no dependency change.
  • src/cli.ts: add the fixed docs preview and docs verify command surfaces and preserve compatibility commands.
  • src/commands/docs/index.ts: separate primary preview lifecycle, compatibility generation lifecycle, status classification, structure validation, and strict verification.
  • src/adapters/mkdocs.ts: add bounded navigation/link discovery and reusable one-build verification helpers.
  • src/schemas/process-state.ts: only additive optional diagnostics if needed; keep schema version 1 and CLI 0.2.0 readability.

Tests

  • tests/unit/mkdocs.test.ts
  • tests/integration/cli.test.ts
  • tests/integration/index-validation.test.ts
  • new tests/integration/docs-preview.test.ts

Test-only fixtures may be created under operating-system temporary directories. Tests must not use live Product Main state, fixed Anuva ports, or sibling working trees.

Product Main guidance

  • AGENTS.md: replace only the Product Main documentation rule after live acceptance.
  • .agents/skills/anuva/anuva-preview-docs/SKILL.md: select preview before edits and one verify after a logical update while retaining exact links.
  • docs/development/AnuvaDevelopmentPolicyPhase3ImplementationPlan.md
  • docs/development/AnuvaDevelopmentPolicyImplementationPlan.md
  • docs/development/DevelopmentProcessPolicy.md
  • docs/development/DocumentationLifecycle.md
  • docs/development/DevelopmentEnvironment.md
  • docs/development/index.md
  • docs/engineering/AnuvaCli.md
  • docs/cli-implementation/cli-implementation-plan.md
  • mkdocs.yml for the Phase 3 plan navigation entry.

Documentation updates will describe the new commands as active only after live acceptance. The exact plan remains the implementation and evidence record.

Explicit exclusions

Phase 3 will not change:

  • application code or tests in Bento, CMS, Python, or Unity;
  • any sibling repository file, including its AGENTS.md or checked-in skills;
  • plugin source, marketplace metadata, installed plugin state, or plugin version;
  • Codex rules or permission files;
  • shared-skill removal;
  • Linear;
  • Cloudflare Tunnel names, tokens, routes, DNS, certificates, or Access policies;
  • canonical documentation publication;
  • the CLI installer, artifact schema, launcher, pointer, or rollback contract;
  • config/toolchain.v1.json, because CLI 0.2.1 remains within the approved >=0.2.0 <0.3.0 range; or
  • arbitrary external listeners, ports, commands, URLs, or paths.

Implementation sequence

After a separate Gate 1 approval:

  1. create codex/development-policy-phase-3 from the then-current main;
  2. add structure-validation helpers and deterministic unit tests;
  3. separate preview restart reasons from content diagnostics;
  4. add docs preview and its owned/stale/external/conflict/stopped integration tests;
  5. add one-build docs verify and its owned/external comparison tests;
  6. preserve and regression-test ensure, wait, validate-indexes, links, status, and stop;
  7. bump package.json to 0.2.1;
  8. update Product Main guidance and this plan's evidence sections;
  9. run source and packaged test gates;
  10. build a clean artifact from a committed head;
  11. open a focused draft PR without readying or merging it; and
  12. present the exact Gate 2 machine mutation before installing the artifact.

Implementation stops if a required behavior needs a new dependency, arbitrary input, schema-version break, sibling write, route mutation, or unowned-process termination.

Test and acceptance matrix

Source tests

bun run check must pass, including:

  • branch, HEAD, and Markdown edits reuse the same healthy owned preview PID;
  • mkdocs.yml, argument, working-directory, or port changes restart only an identity-verified owned PID;
  • unhealthy owned processes restart safely;
  • dead registry entries are removed;
  • reused or mismatched live PIDs are never stopped;
  • external healthy listeners are refused by preview;
  • external listeners are accepted by verify only when every requested page matches the one strict build;
  • conflicting and stopped listeners return distinct deterministic results;
  • one verify invocation performs one strict build for multiple pages;
  • preview and links reject paths outside docs_dir;
  • root index, navigation, local link, orphan, empty-section, and meaningful section-index checks report sorted exact paths;
  • asset and organizational directories do not require indexes;
  • legacy ensure/wait timestamp behavior remains tested; and
  • mutating commands outside the new approval-free preview contract still fail closed without --dry-run or --confirm.

Packaged tests

bun run check:packaged must pass with the existing artifact, installer, launcher, and rollback suites. Add packaged assertions that:

  • the compiled executable exposes docs preview and docs verify;
  • --version, embedded commit, and clean/dirty identity remain exact;
  • an isolated installation can preview and verify a temporary MkDocs fixture without Product Main TypeScript source; and
  • rollback to the prior packaged artifact remains valid.

Product Main live preview

Before live CLI installation, the source build must:

  1. reuse the owned Product Main preview across an uncommitted Markdown edit;
  2. show the edited Phase 3 plan at its exact public URL through live reload;
  3. run one strict verification for every changed Product Main page;
  4. retain the same listener PID for content, branch, and HEAD changes; and
  5. prove a configuration change is still a restart reason in an isolated fixture, not by perturbing the live configuration.

Five-repository read-only acceptance

After Gate 2 installs the clean packaged artifact, run from Product Main using only configured repository keys and existing sibling files:

anuva docs status --all --json
anuva docs preview --repository <key> --file docs/index.md --json
anuva docs verify --repository <key> --file docs/index.md --json
anuva docs links --repository <key> --file docs/index.md --json

Repeat the last three commands for all five configured repositories. Acceptance requires:

  • each local route is healthy through a CLI-owned process;
  • each representative page matches one strict build for its repository;
  • every exact machine-one HTTPS URL is returned;
  • each HTTPS route is opened successfully from an authenticated browser;
  • no Product Main TypeScript source appears in the packaged process tree;
  • no sibling file or Git state changes; and
  • no tunnel, route, DNS, certificate, Access, or token mutation.

Product Main fixture and live-edit tests prove live reload behavior. Editing a sibling repository merely to repeat that proof is prohibited in this phase.

Approval gates

Gate 1: implementation

A separate approval of this exact plan authorizes the listed Product Main source, tests, guidance, managed implementation branch, temporary fixtures, clean 0.2.1 artifact build, and focused draft PR.

It does not authorize a live CLI upgrade, a confirmed toolchain action, a sibling write, a Cloudflare mutation, PR readiness, or merge.

Gate 2: live CLI upgrade and preview acceptance

Before any live installation or process mutation, present:

  • artifact version, build ID, full source commit, dirty state, size, and SHA-256;
  • current installed current and previous targets;
  • proposed version directory and exact pointer transition;
  • whether PATH changes;
  • the exact installer command;
  • the exact owned preview processes that may start or restart;
  • a toolchain dry-run and any requested action;
  • the exact rollback transition and command; and
  • confirmation that Cloudflare and sibling files remain read-only.

Only explicit approval of those concrete effects authorizes installation, rollback testing, inverse rollback, or starting the five owned previews.

Gate 3: review and merge

After the draft PR, source and packaged tests, live installation, rollback and inverse rollback, five-repository acceptance, and strict Product Main previews pass, return the exact reviewed head, PR scope, review threads, checks, mergeability, installed build, preview states, and rollback evidence.

Ready and merge only on a separate explicit user approval guarded to the exact reviewed head. Gate 3 does not authorize Phase 4.

Rollback

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

Before live installation, implementation rollback is ordinary Git reversion plus removal of ignored build output. The Phase 2 CLI and current documentation commands remain active.

After a Gate 2 installation:

  1. run anuva cli rollback --dry-run;
  2. verify the destination is the exact prior packaged 0.2.0 build;
  3. run anuva cli rollback --confirm only within the approved Gate 2;
  4. verify anuva --version, anuva cli status --json, legacy docs ensure/docs wait, and representative links;
  5. run rollback again to restore the validated 0.2.1 build;
  6. verify preview, verify, and five-repository read-only acceptance again; and
  7. retain both packaged versions, the legacy-source target, receipts, and compatibility commands through merge.

Because process-state schema version 1 and all Phase 2 fields remain compatible, rollback must not require deleting machine state or stopping an unowned process. No rollback step deletes shared skills, sibling files, Cloudflare configuration, repository history, secrets, or unrelated processes.

Stop conditions

Stop and revise this plan before implementation if work requires:

  • a write outside Product Main or an operating-system temporary directory;
  • a new npm, Python, or MkDocs dependency;
  • a process-state schema version that CLI 0.2.0 cannot read;
  • termination or adoption of an unowned process;
  • an arbitrary executable, argument, repository, port, URL, or path;
  • a plugin, marketplace, Codex rule, or shared-skill migration;
  • a Cloudflare or canonical-publication mutation;
  • a CLI version outside the existing toolchain range;
  • removal or behavior loss of the compatibility commands before acceptance; or
  • Phase 4 shared-skill redesign.