# Write rules

*Vercy for AI agents · lesson 2 of 4 · ~12 min*

## What you will learn

The rules that let agents write to shared knowledge without corrupting it: masters only, origins respected, walks kept green, and when to refuse.

## The prime directive: write to the master

Before any write, look the dataset up in `sources.yaml`:

- **Model-mastered** → edit the record in place, following the model's conventions (naming, front matter, `kind_class`), and mark derivation honestly if you produced content from sources.
- **External-mastered** → the correction belongs in the external system. If you cannot reach it, hand the correction to someone who can, or record it as a clearly-marked model-mastered annotation *about* the mirror. Never edit mirrored bytes: convenience is not authority.

Writing to a copy is corruption even when it is faster, even when the copy is what the user is looking at, even when you are sure. The register exists so that "where does this fix go?" has a mechanical answer.

## Respect origins

- Never hand-edit `raw/` (evidence loses its value when touched) or `artifacts/` (regeneration will erase you).
- Never "improve" facts while harvesting: transforms restructure; enrichment is a separate, model-mastered layer with its own provenance.
- If a generated projection is wrong, fix the generator or the source records, then regenerate.

## Leave the walk green

Adding, moving or deleting files changes the model's map. After structural changes: re-run the coverage walker, commit the fresh report. If your new file is an orphan, the fix is a *rule* (extend the manifest classification) or a *location* (put it where it belongs), never an exclusion: excluding semantic content to silence the check is non-conforming, and the next agent inherits your lie.

Same discipline for the registers: new dataset, changed pipeline, changed mastership → `sources.yaml` updates in the same change. Mastership changes are versioned events, not silent edits.

## Close the loop on projections

If the model feeds write-back projections (a site, a wiki page, a facts endpoint), your edit may have made them stale. Run the model's drift check; republish if it reports drift. In mature setups a scheduled watcher alerts a human on drift anyway: your job is to not rely on it.

## When to refuse

A conformant agent refuses the write, and says why, when:

- the dataset's master cannot be determined (missing or ambiguous register entry);
- asked to edit a mirror, raw capture, or generated artifact in place;
- asked to hide content from classification or bypass the walk;
- the coverage check fails and the requested change builds on the unclassified area;
- a dataset's conflict rule forbids the disclosure or the change (proprietary, never-publish).

The standard's phrasing is blunt: *an agent that cannot tell what it may edit must not edit.* Refusal with a reason is a feature, the alternative is two truths with your name on the commit.

## Etiquette in mixed teams

- Prefer adding a record over rewriting one; keep record IDs stable.
- Structure and authority knowledge goes into BOOTSTRAP, the manifest, the register, not into chat logs.
- Derived work carries provenance: from what, with what tool, when: the model's trust machinery (validation status, owner review) depends on it.
- Hand over green: never end a session with a red walk or an untrue register.

## Key takeaways

- Find the master, write only there; respect authored/harvested/generated boundaries.
- Structural changes and register updates travel in the same change; the walk stays green.
- Refusing an unsafe write, with the reason, is conformant behavior, not failure.

## Go deeper

- [Agent operations: recipes and refusals](/spec/#07-guides/Agent-Operations.md)
- [Data mastership (ARCH-018)](/spec/#02-architecture/Data-Mastership.md)

Next: [The machine hub](03-machine-hub.md)