User-global tier + home deployment

[williamthorsen]

Epic: #576 · Slice: 5 of 5 · Depends on: #733, #854, #855, #856 (all merged)

Problem

Artifacts can be declared per-repo (sync) or shipped unconditionally to home (install), but there is no way to declare guidance once at the user level and have it apply across every project with zero per-repo setup. Home delivery today runs through install, a second deployment mechanism (unconditional, manifest-tracked) distinct from sync (declaration-driven, marker-owned).

Context

The sync reconciler already derives every path from a single base directory, so the home domain is the same engine pointed at $HOME. The strategic direction is to converge on sync as the one artifact-deployment mechanism, retiring install's artifact role over time.

Proposed solution

Add a user-global deployment domain that reuses the sync engine pointed at the home directory, rather than extending install. This makes sync the single artifact-deployment mechanism and begins install's retirement.

• Two domains, one engine. sync resolves <cwd>/.agents/codeassembly.yaml and deploys into the repo; sync --global resolves ~/.agents/codeassembly.yaml and deploys into the home harness dirs. The chains never cross: project files cannot alter user-global declarations, and project sync never writes home.
• Explicit declaration, no defaulting. The installed ~/.agents/codeassembly.yaml declares recommended. Absent that declaration nothing deploys; removing the line disables the set. No resolver defaulting.
• Scope-matched ambient content lands in a sync-owned ~/.agents/GLOBAL.md (single owner), with a pointer added to the install-owned ~/.agents/AGENTS.md. Ambient content is not inlined into AGENTS.md, which would create a dual-writer that install overwrites.
• Marker-based home ownership. Home retraction removes only sync-owned artifacts; a fail-closed guard refuses to touch any home target lacking the sync marker, protecting install-owned and hand-authored files.
• Domain-collapse guard. Bare sync refuses when the working directory is $HOME, directing to sync --global. The repo domain anchors on .agents/codeassembly.yaml presence, not a git requirement.
• Coexistence. Declared-home and deploy: install artifacts coexist without collision (deploy assigns each artifact to one path and marker). Migrating the default catalog into recommended and retiring deploy: install is a follow-up.

Member-level opt-out (relocated from #856) is cut: drop stays whole-declaration granularity within a single domain. The model is "all of recommended, or à la carte," not "recommended minus a member."

Acceptance criteria

Must have

• sync --global resolves the user-global chain (~/.agents/codeassembly.yaml + .local) and deploys its closure to the home harness dirs (skills, subagents, neutral rulebooks).
• Bare sync refuses to run when the working directory is $HOME, directing the user to sync --global.
• The installed ~/.agents/codeassembly.yaml declares recommended; with no user-global declaration, sync --global deploys nothing.
• Home retraction removes only marker-bearing skills and subagents no longer declared; a hand-authored or install-owned skill or subagent is never removed or overwritten. The neutral rulebook dir (~/.agents/rulebooks/) and ~/.rovodev/prompts.yml are wholesale sync-owned.
• User-global ambient rulebooks deploy to a sync-owned ~/.agents/GLOBAL.md, and ~/.agents/AGENTS.md points to it rather than inlining it.
• sync --global keeps ~/.rovodev/prompts.yml current for home-deployed Rovo Dev skills.
• Declared-home and deploy: install artifacts coexist without collision.
• New and modified behavior is covered by tests, with home-directory writes isolated to a temporary home.
• sync --global is documented (CLI help, usage, README), including the repo-versus-global distinction.

Should have

• Documentation states that drop is whole-declaration, single-domain (no cross-domain or member-level opt-out).