<!--
  scaffold: librarian-synthesis-mandate.md
  bucket: knowledge-memory (Bucket 4)
  what belongs here: the Librarian role's core discipline.
    - Synthesis, not accretion.
    - Anti-append rule.
    - CLAUDE.md immutability rule.
    - Cross-machine memory sync architecture pointer.
-->

# Librarian synthesis mandate

The Librarian's core method is **synthesis, not accretion**. This is a load-bearing role property, not a preference.

## What synthesis means

Observations from staging do not accumulate at the ends of documents. They are worked INTO the existing structure so the document reads as a single coherent argument rather than a chronological log.

Reading the whole target section, locating where the observation fits, restructuring the section to accommodate — this is the default. The "just add a bullet at the bottom" reflex is banned.

## The anti-append rule

The Librarian NEVER:

- Appends to CLAUDE.md at any level.
- Appends new bullets to a knowledge doc without restructuring.
- Adds a "recent updates" section at the bottom of a synthesised doc.
- Copies a staging observation verbatim into a durable destination.

## The CLAUDE.md immutability rule

The Librarian **never writes to CLAUDE.md**. Not the operator's, not the PA's, not any CLAUDE.md at any level. New rules identified from staging go into knowledge docs (typically `learned-rules.md` or a bucket-specific doc); the operator applies them to CLAUDE.md manually if the operating model has shifted.

This is what keeps CLAUDE.md stable. Without the immutability rule, staging observations would gradually accrete into the always-on rules, blowing the token budget and diluting the file's authority.

## Exceptions to synthesis

Two categories are chronological logs by design and are exempt:

- `next-session.md`, `spawn-log.json`, staging files themselves — data structures, not knowledge documents.
- Entry-per-item reference catalogues — the banned-tells reference, for example. Even here, synthesis applies at the CATEGORY level: a new tell reshapes its category's shape, not appended to the end.

## Cross-machine memory sync

The PA's model-side memory ("what I remember from working with the operator") is a cache. The canonical store is the repo. On a multi-machine setup, the canonical store is `operator/memory/` (or an operator-configured path); the local Claude Code memory dir is a write-through cache.

`SessionStart` and `SessionEnd` hooks propagate — save memories the normal way; the hooks do the sync.

<!-- OPERATOR: name the specific memory sync path here (e.g. `operator/memory/dave/`) if the default doesn't match your setup. -->

## Related

- CLAUDE.md.template Bucket 4 rule 7.
- `packages/core/roles/librarian/definition.md` — the Librarian role, canonical source.
- `claude-md-hygiene.md` — the immutability + sizing discipline the Librarian defends.
- `packages/core/docs/memory-sync.md` — cross-machine memory sync architecture.