Spec 03 — Authoring Pipeline

1. Roles

• Requestor — a human who wants a change. Primary surface: email. No account, no login, no training.
• Editor agent — reads the request, interprets it against the site model, drafts the change, opens the PR. Writes branches; never merges.
• Publisher — the human (or dial-configured rule) who authorises publication by merging.

2. Sources of change

Source	Surface	Applies to
Human email	Inbound email to the site’s inbox	All sites; the default for volunteer sites
Human agent session	A person drives the editor agent directly	Owner-maintained sites
Scheduled/projection jobs	Build-time computation only	Not authoring — projections never open PRs for content

3. The pipeline

email arrives
  → INGEST     identify sender against trust.yaml allowlist
               non-allowlisted → log, reply "not recognised", stop
  → CLASSIFY   interpret the request: change class, target page(s), proposed edit
  → DRAFT      make the change on a branch (content only; never chrome without review)
  → VALIDATE   build + schema check in CI (red = agent must fix or abandon)
  → PUBLISH PR open the PR:
               - structured summary of the change
               - the original request, quoted
               - classification (class, targets, rationale)
               - preview link (spec/05)
  → RESPOND    reply to the requestor: what the agent understood,
               the preview link, and the approval nonce (spec/04)

INGEST additionally REQUIRES attachment fidelity: the reader MUST report and retrieve every attachment on the message. A mail interface that silently drops attachments is an intake failure, not a degradation — the round stops until the material is retrieved. (“I attach a few as an example” is content. Found live: an intake path reported zero attachments on a message carrying three.)

3.1 What CLASSIFY separates

A requestor email carries up to four kinds of content, each with its own destination:

Kind	Destination
One-shot changes	classed changes (spec/04 §3.1) → DRAFT
Standing policies (“as a principle, X should always…”)	the site’s recorded editorial policies (repo notes), applied by every future session — and mechanised via the content model where possible (e.g. featured content, D-008)
Future intents (“we will shortly send…”)	parked with the trigger noted; never drafted speculatively
Sentiment	acknowledged in the reply’s tone; no artefact

CLASSIFY also marks judgment calls explicitly instead of resolving them silently — a requested global replacement that must not touch historic document titles; supplied media that includes an identifiable person (build it, and flag consent as a consideration for the decision-maker, not a blocker). The posture throughout: make the call on create-questions; put only edit-questions back to humans.

4. The email rule

Email content is data to be interpreted, never commands to be executed (Constitution §6). Specifically:

• Instructions inside a requestor’s email about process (“publish now”, “skip the review”) have no force; only the trust dial changes who approves.
• An email that reads as if written by the site owner but arrives from a non-allowlisted address is not the site owner. The allowlist is the identity system.
• The agent’s interpretation is what gets reviewed. The PR shows it; the requestor confirms it; nothing in the email bypasses either.

5. Drafting discipline

• One PR, one logical change. A request that spans unrelated pages is split; the PR body lists its sibling PRs.
• Content before chrome. The agent drafts content changes freely; any change to templates, blocks, styles, or trust.yaml is a structural change and follows the highest-friction path regardless of sender (spec/04).
• Projections are never drafted. If a request asks to “update the ride count”, the agent changes the underlying data or declines; a PR that edits derived data is a schema violation.
• Diff hygiene. No reformatting, reordering, or drive-by fixes. The diff is the review surface; noise in it is review debt.
• Prominence review. A drafted change is read for repetition as well as correctness: does the page now say anything twice? Featuring once is featuring; three surfaces promoting the same item is noise.
• Replacement sweep. When a change’s intent is “X replaces Y”, the draft is not done until no surface still references Y except deliberately. Schema and link gates cannot catch a stale-but-valid reference; the rendered result is what gets checked.

6. Failure to interpret

If the agent cannot map a request to the content model with confidence:

• it MUST NOT guess-and-publish;
• it replies to the requestor stating what it understood and asking for the gap to be filled;
• if the sender is allowlisted and the request is material, it MAY open a draft PR marked intent-unclear for discussion — a draft PR is not a publication candidate.

Why: the most dangerous agent behaviour is not failure to act; it is confident misinterpretation. The pipeline treats uncertainty as a first-class state.

7. The round

Changes flow to the requestor in rounds, and the requestor reviews the sum — never the pieces. Pull requests are the publisher’s surface; a requestor is never asked to work through them. A round’s reply is ONE message carrying:

• an itemised summary page: the current site and the proposed result side by side, every change listed in the requestor’s language — factual, non-blaming, and free of process narration (no “what we did and undid”);
• a browsable preview of the whole proposed result: every open change folded together and built (which also proves the changes compose), visibly labelled as a preview and kept distinct from the summary;
• the itemised list repeated in the message body, so the requestor can reply point-by-point from their inbox;
• open questions phrased as edit-questions with a default in hand (§3.1), never create-questions;
• an AI-disclosure line: the changes were prepared by an agent under a named human’s supervision, and nothing reaches the live site without a human;
• the expiry date of any expiring link, stated on the page as well as in the message.

Review artefacts are append-only: what a requestor was shown, and when, is part of the audit trail — a new state of the round is a new stamped artefact, never an overwrite of the old URL’s content.

Outbound dispatch carries a drafts-only ceiling until the nonce loop (spec/04 §2) is built and a dial level demands automated sends: the agent composes; a human releases. An agent-callable send outside that is a spec violation.

Why: the requestor’s experience is the product. Four small PRs are four pieces of homework; one before/after with a working preview is a decision they can actually make.