README.md

@@ -27,7 +27,8 @@ timmy-config/
 ├── cron/                      ← Cron job definitions
 ├── docs/
 │   ├── automation-inventory.md ← Live automation + stale-state inventory
-│   └── ipc-hub-and-spoke-doctrine.md ← Coordinator-first, transport-agnostic fleet IPC doctrine
+│   ├── ipc-hub-and-spoke-doctrine.md ← Coordinator-first, transport-agnostic fleet IPC doctrine
+│   └── coordinator-first-protocol.md ← Coordinator doctrine: intake → triage → route → track → verify → report
 └── training/                  ← Transitional training recipes, not canonical lived data
 ```
 
@@ -54,6 +55,7 @@ For fleet routing semantics over sovereign transport, read
 
 All orchestration (triage, PR review, dispatch) runs via [Huey](https://github.com/coleifer/huey) with SQLite.
 `orchestration.py` + `tasks.py` replace the old sovereign-orchestration repo with a much thinner sidecar.
+Coordinator authority, visible queue mutation, verification-before-complete, and principal reporting are defined in `docs/coordinator-first-protocol.md`.
 
 ```bash
 pip install huey

docs/coordinator-first-protocol.md

@@ -0,0 +1,373 @@
+# Coordinator-first protocol
+
+This doctrine translates the Timmy coordinator lane into one visible operating loop:
+
+intake -> triage -> route -> track -> verify -> report
+
+It applies to any coordinator running through the current sidecar stack:
+- Timmy as the governing local coordinator
+- Allegro as the operations coordinator
+- automation wired through the sidecar, including Huey tasks, playbooks, and wizard-house runtime
+
+The implementation surface may change.
+The coordination truth does not.
+
+## Purpose
+
+The goal is not to invent more process.
+The goal is to make queue mutation, authority boundaries, escalation, and completion proof explicit.
+
+Timmy already has stronger doctrine than generic coordinator systems.
+This protocol keeps that doctrine while making the coordinator loop legible and reviewable.
+
+## Operating invariants
+
+1. Gitea is the shared coordination truth.
+   - issues
+   - pull requests
+   - comments
+   - assignees
+   - labels
+   - linked branches and commits
+   - linked proof artifacts
+
+2. Local-only state is advisory, not authoritative.
+   - tmux panes
+   - local lock files
+   - Huey queue state
+   - scratch notes
+   - transient logs
+   - model-specific internal memory
+
+3. If local state and Gitea disagree, stop mutating the queue until the mismatch is reconciled in Gitea.
+
+4. A worker saying "done" is not enough.
+   COMPLETE requires visible artifact verification.
+
+5. Alexander is not the default ambiguity sink.
+   If work is unclear, the coordinator must either:
+   - request clarification visibly in Gitea
+   - decompose the work into a smaller visible unit
+   - escalate to Timmy for governing judgment
+
+6. The sidecar owns doctrine and coordination rules.
+   The harness may execute the loop, but the repo-visible doctrine in `timmy-config` governs what the loop is allowed to do.
+
+## Standing authorities
+
+### Timmy
+
+Timmy is the governing coordinator.
+
+Timmy may automatically:
+- accept intake into the visible queue
+- set or correct urgency
+- decompose oversized work
+- assign or reassign owners
+- reject duplicate or false-progress work
+- require stronger acceptance criteria
+- require stronger proof before closure
+- verify completion when the proof is visible and sufficient
+- decide whether something belongs in Allegro's lane or requires principal review
+
+Timmy must escalate to Alexander when the issue requires:
+- a change to doctrine, soul, or standing authorities
+- a release or architecture tradeoff with principal-facing consequences
+- an irreversible public commitment made in Alexander's name
+- secrets, credentials, money, or external account authority
+- destructive production action with non-trivial blast radius
+- a true priority conflict between principal goals
+
+### Allegro
+
+Allegro is the operations coordinator.
+
+Allegro may automatically:
+- capture intake into a visible Gitea issue or comment
+- perform first-pass triage
+- assign urgency using this doctrine
+- route work within the audited lane map
+- request clarification or decomposition
+- maintain queue hygiene
+- follow up on stale work
+- re-route bounded work when the current owner is clearly wrong
+- move work into ready-for-verify state when artifacts are posted
+- verify and close routine docs, ops, and queue-hygiene work when proof is explicit and no governing boundary is crossed
+- assemble principal digests and operational reports
+
+Allegro must escalate to Timmy when the issue touches:
+- doctrine, identity, conscience, or standing authority
+- architecture, release shape, or repo-boundary decisions
+- cross-repo decomposition with non-obvious ownership
+- conflicting worker claims
+- missing or weak acceptance criteria on urgent work
+- a proposed COMPLETE state without visible artifacts
+- any action that would materially change what Alexander sees or believes happened
+
+### Workers and builders
+
+Execution agents may:
+- implement the work
+- open or update a PR
+- post progress comments
+- attach proof artifacts
+- report blockers
+- request re-route or decomposition
+
+Execution agents may not treat local notes, local logs, or private session state as queue truth.
+If it matters, it must be visible in Gitea.
+
+### Alexander
+
+Alexander is the principal.
+
+Alexander does not need to see every internal routing note.
+Alexander must see:
+- decisions that require principal judgment
+- urgent incidents that affect live work, safety, or trust
+- verified completions that matter to active priorities
+- concise reports linked to visible artifacts
+
+## Truth surfaces
+
+Use this truth order when deciding what is real:
+
+1. Gitea issue and PR state
+2. Gitea comments that explain coordinator decisions
+3. repo-visible artifacts such as committed docs, branches, commits, and PR descriptions
+4. linked proof artifacts cited from the issue or PR
+5. local-only state used to produce the above
+
+Levels 1 through 4 may justify queue mutation.
+Level 5 alone may not.
+
+## The loop
+
+| Stage | Coordinator job | Required visible artifact | Exit condition |
+|---|---|---|---|
+| Intake | capture the request as a queue item | issue, PR, or issue comment that names the request and source | work exists in Gitea and can be pointed to |
+| Triage | classify repo, scope, urgency, owner lane, and acceptance shape | comment or issue update naming urgency, intended owner lane, and any missing clarity | the next coordinator action is obvious |
+| Route | assign a single owner or split into smaller visible units | assignee change, linked child issues, or route comment | one owner has one bounded next move |
+| Track | keep status current and kill invisible drift | progress comment, blocker comment, linked PR, or visible state change | queue state matches reality |
+| Verify | compare artifacts to acceptance criteria and proof standard | verification comment citing proof | proof is sufficient or the work is bounced back |
+| Report | compress what matters for operators and principal | linked digest, summary comment, or review note | Alexander can see the state change without reading internal chatter |
+
+## Intake rules
+
+Intake is complete only when the request is visible in Gitea.
+
+If a request arrives through another channel, the coordinator must first turn it into one of:
+- a new issue
+- a comment on the governing issue
+- a PR linked to the governing issue
+
+The intake artifact must answer:
+- what is being asked
+- which repo owns it
+- whether it is new work, a correction, or a blocker on existing work
+
+Invisible intake is forbidden.
+A coordinator may keep scratch notes, but scratch notes do not create queue reality.
+
+## Triage rules
+
+Triage produces five outputs:
+- owner repo
+- urgency class
+- owner lane
+- acceptance shape
+- escalation need, if any
+
+A triaged item should answer:
+- Is this live pain, active priority, backlog, or research?
+- Is the scope small enough for one owner?
+- Are the acceptance criteria visible and testable?
+- Is this a Timmy judgment issue, an Allegro routing issue, or a builder issue?
+- Does Alexander need to see this now, later, or not at all unless it changes state?
+
+If the work spans more than one repo or clearly exceeds one bounded owner move, the coordinator should split it before routing implementation.
+
+## Urgency classes
+
+| Class | Meaning | Default coordinator response | Alexander visibility |
+|---|---|---|---|
+| U0 - Crisis | safety, security, data loss, production-down, Gitea-down, or anything that can burn trust immediately | interrupt normal queue, page Timmy, make the incident visible now | immediate |
+| U1 - Hot | blocks active principal work, active release, broken automation, red path on current work | route in the current cycle and track closely | visible now if it affects current priorities or persists |
+| U2 - Active | important current-cycle work with clear acceptance criteria | route normally and keep visible progress | include in digest unless escalated |
+| U3 - Backlog | useful work with no current pain | batch triage and route by capacity | digest only |
+| U4 - Cold | vague ideas, research debt, or deferred work with no execution owner yet | keep visible, do not force execution | optional unless promoted |
+
+Urgency may be raised or lowered only with a visible reason.
+Silent priority drift is coordinator failure.
+
+## Escalation rules
+
+Escalation is required when any of the following becomes true:
+
+1. Authority boundary crossed
+   - Allegro hits doctrine, architecture, release, or identity questions
+   - any coordinator action would change principal-facing meaning
+
+2. Proof boundary crossed
+   - a worker claims done without visible artifacts
+   - the proof contradicts the claim
+   - the only evidence is local logs or private notes
+
+3. Scope boundary crossed
+   - the task is wider than one owner
+   - the task crosses repos without an explicit split
+   - the acceptance criteria changed materially mid-flight
+
+4. Time boundary crossed
+   - U0 has no visible owner immediately
+   - U1 shows no visible movement in the current cycle
+   - any item has stale local progress that is not reflected in Gitea
+
+5. Trust boundary crossed
+   - duplicate work appears
+   - one worker's claim conflicts with another's
+   - Gitea state and runtime state disagree
+
+Default escalation path:
+- worker -> Allegro for routing and state hygiene
+- Allegro -> Timmy for governing judgment
+- Timmy -> Alexander only for principal decisions or immediate trust-risk events
+
+Do not write "needs human review" as a generic sink.
+Name the exact decision that needs principal authority.
+If the decision is not principal in nature, keep it inside the coordinator loop.
+
+## Route rules
+
+Routing should prefer one owner per visible unit.
+
+The coordinator may automatically:
+- assign one execution owner
+- split work into child issues
+- re-route obviously misassigned work
+- hold work in triage when acceptance criteria are weak
+
+The coordinator should not:
+- assign speculative ideation directly to a builder
+- assign multi-repo ambiguity as if it were a one-file patch
+- hide re-routing decisions in local notes
+- keep live work unassigned while claiming it is under control
+
+Every routed item should make the next expected artifact explicit.
+Examples:
+- open a PR
+- post a design note
+- attach command output
+- attach screenshot proof outside the repo and link it from the issue or PR
+
+## Track rules
+
+Tracking exists to keep the queue honest.
+
+Acceptable tracking artifacts include:
+- assignee changes
+- linked PRs
+- blocker comments
+- reroute comments
+- verification requests
+- digest references
+
+Tracking does not mean constant chatter.
+It means that a third party can open the issue and tell what is happening without access to private local state.
+
+If a worker is making progress locally but Gitea still looks idle, the coordinator must fix the visibility gap.
+
+## Verify rules
+
+Verification is the gate before COMPLETE.
+
+COMPLETE means one of:
+- the issue is closed with proof
+- the PR is merged with proof
+- the governing issue records that the acceptance criteria were met by linked artifacts
+
+Minimum rule:
+no artifact verification, no COMPLETE.
+
+Verification must cite visible artifacts that match the kind of work done.
+
+| Work type | Minimum proof |
+|---|---|
+| docs / doctrine | commit or PR link plus a verification note naming the changed sections |
+| code / config | commit or PR link plus exact command output, test result, or other world-state evidence |
+| ops / runtime | command output, health check, log citation, or other world-state proof linked from the issue or PR |
+| visual / UI | screenshot proof linked from the issue or PR, with a note saying what it proves |
+| routing / coordination | assignee change, linked issue or PR, and a visible comment explaining the state change |
+
+The proof standard in [`CONTRIBUTING.md`](../CONTRIBUTING.md) applies here.
+This protocol does not weaken it.
+
+If proof is missing or weak, the coordinator must bounce the work back into route or track.
+"Looks right" is not verification.
+"The logs seemed good" is not verification.
+A private local transcript is not verification.
+
+## Report rules
+
+Reporting compresses truth for the next reader.
+
+A good report answers:
+- what changed
+- what is blocked
+- what was verified
+- what needs a decision
+- where the proof lives
+
+### Alexander-facing report
+
+Alexander should normally see only:
+- verified completions that matter to active priorities
+- hot blockers and incidents
+- decisions that need principal judgment
+- a concise backlog or cycle summary linked to Gitea artifacts
+
+### Internal coordinator report
+
+Internal coordinator material may include:
+- candidate routes not yet committed
+- stale-lane heuristics
+- provider or model-level routing notes
+- reminder lists and follow-up timing
+- advisory runtime observations
+
+Internal coordinator material may help operations.
+It does not become truth until it is written back to Gitea or the repo.
+
+## Principal visibility ladder
+
+| Level | What it contains | Who it is for |
+|---|---|---|
+| L0 - Internal advisory | scratch triage, provisional scoring, local runtime notes, reminders | coordinators only |
+| L1 - Visible execution truth | issue state, PR state, assignee, labels, linked artifacts, verification comments | everyone, including Alexander if he opens Gitea |
+| L2 - Principal digest | concise summaries of verified progress, blockers, and needed decisions | Alexander |
+| L3 - Immediate escalation | crisis, trust-risk, security, production-down, or principal-blocking events | Alexander now |
+
+The coordinator should keep as much noise as possible in L0.
+The coordinator must ensure anything decision-relevant reaches L1, L2, or L3.
+
+## What this protocol forbids
+
+This doctrine forbids:
+- invisible queue mutation
+- COMPLETE without artifacts
+- using local logs as the only evidence of completion
+- routing by private memory alone
+- escalating ambiguity to Alexander by default
+- letting sidecar automation create a shadow queue outside Gitea
+
+## Success condition
+
+The protocol is working when:
+- new work becomes visible quickly
+- routing is legible
+- urgency changes have reasons
+- local automation can help without becoming a hidden state machine
+- Alexander sees the things that matter and not the chatter that does not
+- completed work can be proven from visible artifacts rather than trust in a local machine
+
+*Sovereignty and service always.*

docs/fleet-vocabulary.md

@@ -30,6 +30,9 @@ This is the canonical reference for how we talk, how we work, and what we mean.
 ### Sidecar Architecture
 Never fork hermes-agent. Pull upstream like any dependency. Everything custom lives in timmy-config. deploy.sh overlays it onto ~/.hermes/. The engine is theirs. The driver's seat is ours.
 
+### Coordinator-First Loop
+One coordinator lane owns intake, triage, route, track, verify, and report. Queue truth stays in Gitea and visible artifacts, not private local notes. Timmy holds governing judgment. Allegro holds routing tempo and queue hygiene. See `coordinator-first-protocol.md`.
+
 ### Lazarus Pit
 When any wizard goes down, all hands converge to bring them back. Protocol: inspect config, patch model tag, restart service, smoke test, confirm in Telegram.