#1068 Deliver ambient rulebooks mechanically, retiring GLOBAL.md

[williamthorsen]

What

A rule declared in a rulebook holds in every session, on both Claude Code and Rovo Dev. Previously it held only when an agent chose to look it up, so one session could obey it and the next ignore it, with nothing to show which had happened. Claude Code's built-in Explore and Plan agents are the exception; they do not pick up global rules.

Machine-specific guidance can be declared through a local source rather than committed to the repository.

~/.agents/GLOBAL.md is retired: sync --global removes it, preserving any hand-written content. Upgrading requires running install once before the first sync --global.

Why

A rulebook declared ambient reached an agent's context only when that agent elected to follow a discovery instruction and read the file holding it. The omission was silent by construction: no error, no failing check, and a skipped read indistinguishable from a read whose rules went unapplied. Declared guidance could therefore go missing with nothing to signal it, and captured sessions record both failure modes.

Details

🎉 Features

• A co-writing contract lets install and sync share one file: the guidance templates carry an empty region delimited by <!-- codeassembly-ambient:start --> / <!-- codeassembly-ambient:end -->, so the region's location is install's and its content is sync's. ambient-region.ts supplies the transforms as pure string functions.
• install splices existing region content into every re-render and excludes it from drift detection. computeContentHash strips region content before hashing; files carrying no markers hash over their raw bytes unchanged, so stored hashes stay valid and no manifest migration is required.
• sync --global injects the resolved ambient set into each targeted harness's region, regenerating it wholesale on each run. HarnessConfig gains guidanceFileName so the target resolves per harness.
• A guidance file that is missing or carries no region is skipped with a warning naming the remedy, so a not-yet-upgraded install degrades delivery for that harness alone rather than failing the sync.
• sync --global retires a legacy ~/.agents/GLOBAL.md: sync-owned blocks are stripped, and the file is deleted only when nothing hand-written remains.

🐛 Bug fixes

• sync --global --dry-run probes each targeted guidance file and previews the skip the real run would take, rather than promising an injection the run would decline.

♻️ Refactoring

• SyncDomain's ambientHostPath becomes a discriminated ambient union — host-file for the repo domain, harness-regions for the home domain — so the home domain no longer names a host file it does not write, and the compiler rules out reaching host-file logic without a path.
• Ambient delivery, host-file state reading, dry-run target description, and legacy retirement move out of reconcileDomain into named helpers. probeAmbientTarget is the single classification the real run and the dry-run reporter both consume, which is what keeps the two in agreement.

🧪 Tests

• ambient-region.test.ts covers the shapes that break string-region code: absent region, empty region, unclosed open marker, unpaired close marker, idempotent re-injection, and bodies containing $-sequences.
• Install tests pin the splice across a deliberately changed template (so preservation is exercised as a genuine splice, not a skipped re-render), region content excluded from drift, hand edits outside the region still detected as drift, and hash equality across an empty and a filled region.
• Sync tests cover per-harness injection, both warn-and-skip paths, dry-run previews for injection and for skip, and all three legacy-retirement paths plus the dry-run guard ahead of the delete.

📚 Documentation

• The project-discovery instruction now names only reads that remain an agent's responsibility; the GLOBAL.md and preferences.yaml lines are dropped.
• README.md and content/guidance/README.md document the region contract, the install-before-sync --global upgrade order, and the machine-local source channel for per-machine ambient content, including the guidance/rulebooks/<slug>.md layout it requires.
• The mechanical-delivery claim is scoped to the home domain; the project domain's bullet names its own bridge and states that delivery there carries no mechanical guarantee until the repo wires the import.

Closes #1068

[github-actions]

Dependency audit

Production dependency audit passed.