Anuva Development Process Policy

Status and authority

This policy is the high-level source of truth for Anuva development work. It defines how Codex App, the Anuva development plugin, the guarded Anuva CLI, Linear, GitHub, repository Markdown, and machine-specific documentation previews divide responsibility.

Policy version: 0.1

Rollout status: Phases 1 through 5 complete. The risk model, ownership decisions, plugin foundation, packaged CLI, fixed toolchain contract, live installation, rollback, and five-repository documentation-preview acceptance are verified. PR #23 merged Phase 2 on 2026-07-29. PR #25 merged Phase 3 as a02084cc9628973f5a965512a48486ba51c979eb. Phase 4 source and installed version 0.2.0 contain the twelve-skill catalog. Machine one verified fresh-process discovery, a source-backed 0.1.0 rollback, inverse rollback, and five-repository acceptance. PR #27 merged Phase 4 as 7773e5db744e94a3ede35482c939210701f70527. Phase 5 removed checked-in shared skills after fresh-process plugin acceptance. Bento PR #8 merged as 1ea2155dc706c222776624c1a6f05ace2ab25a8f, Web PR #42 as 109ccd90de7d0f9bed488dfae02d2963600a40f6, Python PR

20 as `596190b65e64cfe7df124083df1d9ded904af026`, Unity PR #9 as

326f457817e03532d29fb1edb5ea997a912ee660, and Product Main PR #29 as 7270381f562b48dbedc65e2c61392867ed9da486. Post-merge acceptance and managed branch cleanup passed. Phase 6 delivered the minimal-rule policy, closed tooling, machine-one rules lifecycle, and clean-machine documentation. The second machine is unavailable; on 2026-07-31 the user deferred its replication and allowed Phase 7 planning to proceed. That decision is a rollout-order exception, not evidence of machine-two or cross-machine acceptance.

Phase 7 planning PR #34 merged as 117f7241f6f3e18440afdf49b11221d8fde5b80b. Gate 2 machine-one and cross-repository acceptance then passed with clean repository baselines, plugin-qualified routing in all five source repositories, no duplicated shared skills, no obsolete active compatibility invocation, and no tracked cleanup target. Plugin 0.2.0, the twelve-skill inventory, active and previous CLI pointers, canonical rules, and fixed toolchain remain unchanged. A fresh five-site generated candidate exists only as local evidence; canonical publication remains separately gated. Machine two remains deferred and must not be reported as accepted.

The one-time Product Main bootstrap authorization recorded in the implementation plan permits this policy and the initial plugin skeleton to be created without a Linear issue. It does not authorize later CLI, rules, MkDocs, or cross-repository migration work.

Policy objectives

Anuva development must:

optimize for a solo developer without sacrificing recovery or traceability;
align approval gates with risk, external effect, and user intent;
keep product decisions and shared application contracts in Product Main and Linear;
keep routine repository and development-process work free of unnecessary Linear ceremony;
preserve repository ownership and repository-scoped writes;
use reusable skills for judgment and a narrow CLI for deterministic side effects; and
keep documentation previews convenient while reserving strict verification for meaningful delivery gates.

Work classification

Classify every requested mutation before changing files.

Lane	Typical scope	Linear	Durable planning	User gates
Product change	User-visible capability, shared application contract, migration, auth, billing, deployment, release, or multi-repository behavior	Required Product Main parent and repository children where needed	Product Main change documents and repository plans	Product-plan approval and final delivery approval
Material single-repository implementation	Significant repository-owned behavior without a shared-contract change	Optional when the user wants durable prioritization or coordination	Proportionate repository plan	Plan approval and merge approval
Routine repository change	Local bug fix, tests, refactor, dependency-neutral maintenance, or local technical docs	Not required	Task or PR description unless complexity warrants more	The request authorizes implementation; pause before merge
Development-process change	Shared skills, plugin, CLI workflow, development docs, toolchain policy, rules, or preview behavior	Not required	Product Main development-process plan or PR description	Material plan approval and final multi-PR merge approval
Machine/environment operation	Toolchain bootstrap, preview processes, tunnel connector, or health checks	Not required	Machine-readable receipts and a fixed manifest where applicable	Gate installation, upgrade, removal, secrets, tunnel administration, or destructive stop

The routine and development-process lanes must reject product behavior, application schemas, migrations, authentication or authorization, privacy, security, billing, deployment architecture, release coordination, and unclear cross-repository contracts. Route those concerns to Product Main.

Approval policy

An explicit request authorizes reversible, in-scope implementation work. Codex may perform the following without a second conversational approval:

read configured Anuva repositories and inspect Git, GitHub, Linear, docs, and local service state;
create or update requested files in the active repository;
create a managed branch for the requested routine or development-process change;
run non-destructive validation and affected-scope tests;
start or health-check an owned documentation preview;
return local and remote preview links; and
execute a typed --confirm form when the user's current request already authorized that exact class of mutation.

Codex must pause before:

approving or materially revising a product or high-risk implementation plan;
merging unless the current request explicitly authorizes review and completion;
deleting non-managed branches or user files;
destructive cleanup without a previously validated managed target;
changing Linear product scope, priority, ownership, or terminal state outside its approved workflow;
installing, upgrading, or removing machine-level tools;
changing authentication, authorization, secrets, billing, data, migrations, deployment architecture, Cloudflare routes, Access policies, DNS, certificates, or tunnel tokens;
expanding from one repository into another repository's product-owned files; or
continuing after failed required checks, review findings, merge conflicts, a newly discovered shared contract, or material scope growth.

A CLI --confirm flag selects the execution form of an already authorized operation. It is not a substitute for a workflow approval and does not create a new gate when the user already approved the exact action.

Responsibility boundaries

Surface	Owns
Codex App	Development conversation, implementation, review, and explicit decisions
`anuva-development` plugin	Shared workflow judgment, routing, risk classification, and repository-aware procedure
Anuva CLI	Typed, deterministic, allowlisted reads and mutations
Linear	Product intent, priority, cross-repository coordination, and implementation handoffs
GitHub	Branches, commits, pull requests, reviews, checks, merges, and immutable delivery history
Repository Markdown	Durable policy, plans, architecture, decisions, operating guidance, and useful evidence
Machine-specific MkDocs sites	Convenient previews of current working trees
`anuva.girishd.com`	Manually published canonical aggregate

Product Main owns this policy, shared Anuva workflow skills, the Anuva CLI, machine-toolchain policy, documentation-preview contracts, and cross-repository process acceptance. Implementation repositories own product code, tests, repository-specific technical documentation, framework guidance, assets, protocols, and affected-scope verification.

Repository and sandbox boundary

C:\Anuva\dev is the shared read boundary for Anuva development machines. Ordinary writes remain limited to the active repository and temporary directories.

Product Main may update sibling repositories only through a future named, allowlisted development-process operation. That operation must validate the target repository and process-only path class. It must never become a general cross-repository writer or application-code executor.

Effective permissions must be verified from the active Codex task. Do not assume a configuration file was honored. A session-only read-directory grant is a recovery mechanism, not the normal workspace model.

Shared skill distribution

The Product Main-owned anuva-development plugin is the canonical distribution mechanism for shared Anuva workflow skills. It is skills-only unless a later approved requirement proves that a hook or MCP server is necessary. The plugin must not add a custom UI or central process-sync workflow during the foundation rollout.

Phase 4 source version 0.2.0 contains the shared product, tracked-issue, repository, development-process, preview, environment, and toolchain skills. Routine and material repository work are issue-free by default; standalone Linear tracking is available only when the user explicitly requests it. Development-process work is explicit-only in Product Main and creates no Linear issue.

Repository AGENTS.md files remain authoritative for repository-specific product boundaries and affected-scope checks. Shared plugin skills must read those instructions, run only relevant checks, explain skipped expensive checks, and stop when repository guidance conflicts with shared policy.

The Phase 5 compatibility period is closed on machine one. Checked-in shared skill copies were removed only after verification of:

installation and version inspection;
discovery from a new Codex task in every Anuva repository;
representative product, implementation, review, preview, environment, and toolchain scenarios;
repository-owned placement of repository-specific verification;
upgrade and rollback; and
migration of active prompts, docs, and AGENTS.md references to the installed skill identity.

Historical change records are immutable and are not rewritten during this migration.

Version 0.2.0 is the installed active workflow on machine one and the canonical shared workflow-skill source in Product Main, Bento, Web, Python, and Unity. Phase 5 post-merge acceptance proved plugin-qualified discovery and routing in every repository, removed all approved duplicated shared copies, and preserved Web's repository-local Mastra and text-to-speech skills. Historical change records remain unchanged.

CLI and toolchain policy

The Anuva CLI must remain an allowlisted executor, never a shell wrapper, generic workflow engine, arbitrary package installer, or YAML step runner. Every mutating command must validate typed inputs, repository identity, paths, current state, and the intended effect; use a scoped lock; verify the result; and write a redacted receipt.

Phase 2 implements a packaged, versioned artifact that runs without Product Main source access and supports atomic upgrade and rollback. The source-backed launcher remains operative until a clean committed artifact, exact checksum, pointer transition, and rollback command pass the separate live-installation gate. The first packaged installation must preserve that source launcher as the closed, checksum-manifested legacy-source rollback target before replacing the stable launcher; arbitrary rollback paths remain prohibited.

Machine one passed that live-installation gate on 2026-07-29 with packaged build 0.2.0-gc8776c067168. Its final active target is the packaged build and its validated previous target is legacy-source. Gate 3 review passed and PR #23 merged at 9c1fe7ef9ebf2c6ce65dc89844c46285a725ca6a. Phase 3 Gate 1 source implementation and Gate 2 acceptance completed on the isolated Phase 3 branch. Phase 3 established current=0.2.1-g3dd30bca40f1 with previous=0.2.0-gc8776c067168; rollback and inverse rollback were verified, and the checksum-manifested legacy-source target remains installed. Gate 3 review passed and PR #25 merged at a02084cc9628973f5a965512a48486ba51c979eb.

Phase 5 acceptance installed exact clean packaged build 0.2.1-g2fecf51439fc with SHA-256 e2f5bf820b0c1dd35eef6103a5335265387c9919cbd19f8bf4ab14f29186a90b using -SkipPathUpdate. Machine one now has current=0.2.1-g2fecf51439fc and previous=0.2.1-g3dd30bca40f1. Install receipt 20260730T050047Z-cli-install-0e3b, rollback receipt 20260730T050148Z-cli-rollback-1f64, and inverse-rollback receipt 20260730T050233Z-cli-rollback-80c9 prove the approved forward and recovery paths. PR #29 merged the corresponding validator boundary as 7270381f562b48dbedc65e2c61392867ed9da486.

Shared machine tools are evaluated against the bundled Product Main-owned config/toolchain.v1.json manifest. Repository dependencies remain repository-local and lockfile or environment managed. Toolchain diagnosis, snapshot, and dry-run are read-only; installation, upgrade, and removal remain explicit user gates.

Codex rules and machine replication policy

Product Main owns the reviewed rule source at config/codex/default.rules. Retain reusable allowance only for the guarded Anuva CLI, direct read-only GitHub inspection, justified direct remote-head inspection, and named repository checks. Direct Git and GitHub mutations plus command-string wrappers remain prompted. Destructive hard reset, forced clean, and repository deletion are forbidden. Arbitrary runtimes, patch helpers, file operations, and temporary exact commands receive no reusable rule.

Every rule includes positive and negative examples. Test the complete decision matrix through codex execpolicy check with bun run check:rules. Skills and agents run reusable commands directly and separately rather than embedding them in compound PowerShell or cmd.exe payloads.

The active user rule file is machine state. Install, rollback, and inverse rollback require a checksum-bound dry run, exact approval, atomic replacement, redacted receipt, and Codex restart. A tracked candidate or passing source test does not authorize installation.

The Windows Development Machine Bootstrap is the durable machine-two procedure. It fixes repository identities and ports, derives tools from the committed manifest, preserves a source-backed first-install CLI rollback target, recreates only sanitized Codex settings, installs the local plugin through its marketplace, verifies Cloudflare read-only, and records a non-secret comparable snapshot. A missing Cloudflare object or required secret stops replication; Phase 6 does not authorize repair or administration.

Machine-two replication is currently deferred. The procedure, gates, rollback, and acceptance contract remain authoritative and must be rerun from the then-current Product Main commit when the machine becomes available. Later phases may complete machine-one process cleanup while recording this exception, but must never state or imply that two-machine acceptance passed.

Documentation policy

Machine-specific MkDocs sites are working-tree previews, not release artifacts. The target design separates:

preview: start or health-check an owned server, rely on live reload, and return exact URLs; and
verification: validate navigation and links, run one strict build for the logical update, and verify selected served pages at a material gate.

Phase 3 makes docs preview and docs verify the active machine contract. Preview is timestamp-free and approval-free for a CLI-owned reversible process; verification performs meaningful structure checks, one strict build, and exact served-page comparison for the logical update. The preserved docs ensure, docs wait, and docs validate-indexes commands are rollback compatibility, not the normal workflow. Follow Documentation Lifecycle. Canonical publication remains manual.

Cloudflare routes must remain Access-protected. No workflow may automatically create or delete tunnels, routes, DNS records, certificates, Access policies, or tunnel tokens.

Durable records

Use durable artifacts in proportion to the work:

Product changes keep Product Main change documents and repository handoffs.
Complex, high-risk, long-running, recovery-sensitive, or cross-repository implementation keeps an implementation plan and useful execution evidence.
Routine work may use the task and PR description plus tests and updated behavior documentation.
Development-process work keeps one Product Main plan and repository impact when material.
Machine operations keep non-secret diagnostics and receipts.

Do not require ImplementationPlan.md, ImplementationLog.md, and CompletionReport.md for a small local fix when they add no durable value.

Conflict and escalation rules

Stop and request direction when:

the requested lane and discovered scope disagree;
repository instructions conflict with this policy or an installed shared skill;
implementation differs materially from an approved plan;
required evidence fails;
ownership is uncertain; or
safe completion needs new authority or a broader external mutation.

Generated HTML, plugin caches, and machine receipts are not editable policy sources. Update Product Main Markdown and plugin source, then regenerate or reinstall through the approved workflow.

Rollout control

The phased implementation plan governs migration order. Each phase must preserve the preceding rollback path. Broader CLI, rules, MkDocs, and cross-repository changes require a separately presented exact implementation scope and the approval gate defined for development-process work.