8 added, 0 removed. Audit A to A.
# Gitmoot
Gitmoot is a local-first coordinator for AI agents working across repositories,
goals, reviews, pull request comments, daemon jobs, branch locks, agent
templates (including GitHub-backed publish/pull), current-chat prompt import,
multi-agent orchestration (the Orchestra delegations DAG), heartbeat schedules,
declared multi-stage pipelines, an outbound event stream, and Codex, Claude Code,
Kimi Code, omp, or shell runtime workflows.
This file is the machine-readable index of the Gitmoot docs — agents should
start here, then open [`llms-full.txt`](https://gitmoot.io/llms-full.txt) for the
full expanded context.
Native review verdicts return `changes_requested` to the requester's org role
by default. Unattended implement fix dispatch is a durable per-PR opt-in.
+ A pull request that changes the `**Current mode:` marker in `AGENTS.md` is held
+ until an exact-head reconciliation row exists:
+ `[workload-mode-reconciliation repo=<owner/repo> pr=<n> head=<40-char reviewed head> mode=<THROUGHPUT|STEADY|DRAIN> decision_note=<note id|none>]`.
+ The decision itself is an append-only `[operating-mode repo=<owner/repo> mode=<mode>]`
+ note; `decision_note=none` means the PR is the decision. The newest decision
+ wins, an unreadable one supersedes rather than reading as absent, and a hold is
+ retryable and bounded by the gate `timeout` or 24h from the episode's start.
+
## Start Here
- [Introduction](https://gitmoot.io/docs/intro): What Gitmoot is and when to use it.
- [Install](https://gitmoot.io/docs/getting-started/install): Install and verify Gitmoot.
- [Quick Start](https://gitmoot.io/docs/getting-started/quick-start): Ask an agent to install Gitmoot, register a repo, start a planner, and route work.
- [PR Comment Workflow](https://gitmoot.io/docs/workflows/pr-comment-workflow): Route auditable work from GitHub comments — `/gitmoot` commands, bare `@agent` mentions, and resuming paused orchestrations.
- [Planner And Goal Workflow](https://gitmoot.io/docs/workflows/planner-goal-workflow): Create structured plans and goal files; plan-gated implement holds implementation until a recorded plan is explicitly approved.
- [Template Capture Workflow](https://gitmoot.io/docs/workflows/template-capture-workflow): Turn a current chat workflow into a reviewed reusable template, and back templates up to a GitHub repo (publish/pull).
- [Review Agent Workflow](https://gitmoot.io/docs/workflows/review-agent-workflow): Register a strict review-only agent and route PR reviews to it; local CLI and native engine dispatch refuse a homogeneous succeeded decision at the unchanged exact head, emit `review_loop_detected`, and never serve the prior verdict as a cached result.
- [Review Agent Workflow](https://gitmoot.io/docs/workflows/review-agent-workflow): Register a strict review-only agent, pair local reviews with an implementation-capable `--lead`, refuse invalid fix routing before spending a review session, run engine-requested fixes in fail-closed independent writable per-job clones, and apply global or per-repository blocking severity so sub-threshold findings remain visible without restarting the fix loop.
- [Coordinator Recipes Workflow](https://gitmoot.io/docs/workflows/coordinator-recipes-workflow): One-command orchestras via `orchestrate --recipe review-panel|decompose-and-verify|verifier` with ephemeral workers.
- [Run Jobs In Parallel On A Repo](https://gitmoot.io/docs/workflows/parallel-jobs-workflow): Use `--parallel N` (or `--workers N`, now auto-`pool`) to run a repo's queued jobs N-wide; the two serialization layers (checkout lock + runtime session lock); per-job exact-head review worktrees, writable on-branch review-fix clones, and committed-tip ask isolation; SIGHUP warm reload, per-repo `max_parallel`, the `[admission]` host budget, and `[github]` ETag polling, adaptive idle cadence, local call accounting, and secondary-rate-limit backoff.
- [Heartbeat Schedules Workflow](https://gitmoot.io/docs/workflows/heartbeat-schedules-workflow): Recurring agent work — `gitmoot agent heartbeat add` enqueues an ask/review (read-only) or policy-gated implement job on an interval, with an optional per-heartbeat `--runtime` override.
- [Pipelines Workflow](https://gitmoot.io/docs/workflows/pipelines-workflow): Run a fixed DAG of shell or managed-agent stages; publish/list/pull reviewable pipeline bundles through a private-by-default GitHub catalog with no-op republish diffs, or export/import the same directory offline. Opt-in shell-only service exposure adds bounded typed schemas, reserved env-only input delivery, random run ids, atomic rate/concurrency admission, detached worktrees, offline store-outcome proofs, authenticated delivery of proof-bound `out/` artifacts, and sanitized public digest-only receipts; the authenticated listener remains loopback-only by default. Pipeline-scoped secrets retain deny-by-default `env_keys`, shared key grants, and proxied loopback leases. Off by default.
## Concepts
- [Local-First Coordination](https://gitmoot.io/docs/concepts/local-first-coordination): Why state lives in local SQLite and GitHub stays the audit surface.
- [Agents, Agent Templates, Jobs, And Locks](https://gitmoot.io/docs/concepts/agents-templates-jobs-locks): The core object model — agent identities, template snapshots, job lifecycle, and the three lock kinds.
- [Agent Persistent Memory](https://gitmoot.io/docs/concepts/agent-memory): Off-by-default repo-filtered fact memory (SQLite + FTS5); explicit or `[memory].default_enroll` enrollment with an `agent start` status notice; observation-mode read/write model; deterministic failure and success distill; opt-in durable insight harvest that stages shared, repo-scoped, low-trust pending observations and can never auto-confirm them; the explicit shared pool with author preservation; private-plus-shared prompt injection with 1-hop linked facts, an on-demand recall footer, and best-effort per-fact injection/direct-recall usage telemetry; `memory ingest sweep` over configured sources; opt-in `[memory].ingest_auto_confirm` for allowlisted ingest/chat/workflow sources; provenance-prefix retirement; lossless grooming plus review-only never-used flags; automatic cluster hierarchy; built-in memory pipelines; and the memory CLI, including `memory recall "<query>" --expand` for FTS5/BM25 lookup plus linked neighbors.
## Dashboard
- [Dashboard Overview](https://gitmoot.io/docs/dashboard/overview): The read-only live web dashboard (`gitmoot dashboard --web [--addr host:port]`) over the local store — launching, the URL route table including `/comms`, shared fleet-activity SSE, auto-refresh cadences (12s polls, 15s runs, SSE per-run graph), mobile support, operator-visible private data, and the localhost-default/no-auth security model.
- [Dashboard Views](https://gitmoot.io/docs/dashboard/views): Overview and Org distinguish live Herdr sessions from engine jobs, decorate the preserved role tree with task/status/turn detail, and label no-session, source-down, and filter-empty states; Comms is the read-only org escalation inbox with complete unresolved-workflow discovery, note deep links, filters, and CLI-only resolution via `gitmoot org escalate resolve`; the reference also covers Graph, Galaxy, Jobs, Pipelines, Workflows, Brain, Agents, Charts, Health, and Attention.
## References
- [CLI Reference](https://gitmoot.io/docs/reference/cli): Commands for install, home/config, daemon operations (including stale advertised-log detection and the systemd journal fallback), watched repos, dashboard, agents (including `agent show`'s unchanged `runtime_ref` field plus additive pinned-session and last-successful-use metadata), orchestrate, org role registry/escalation/recycle, safe org seat creation with optional create-now-bind-later roles, canonical stable pane-id persistence from literal ids or unique exact labels, creator-inherited parent/scope, and opt-in merge authority, deterministic doctor warnings for absent or stale org-role activity using `org_role_presence.last_seen_at` and configured `recycle_after`, exact-head bounded `org await review` fact subscriptions with atomic subscribe-and-recheck, queryable expiry, and delivery-only addressed wakes, downward-only directives with `send`/`ack`/`cancel`/`done` carrying three distinct disciplines — ack by the target or an ancestor, cancel by the sender, and done restricted to the target SUBTREE so an ancestor cannot certify work it commissioned — with `done` ending the obligation's TTL nudges, per-phase finite directive nudge ladders whose completion phase ends in a typed org:directive-exhausted marker note plus a row stamp, so a terminal ladder stays discoverable in the workflow journal, population-sized TTL sweep windows, durable coalesced nag delivery, and Claude quota-unavailable dispatch holds, Herdr-observed archived-seat roster exclusion at one choke-point (chart, status, health, sweeps, nudge ladders, presence) with parked directives and a stale-observation doctor warning, pipelines, jobs, locks, goals, memory, including parent-linked session jobs with explicit caller-reported model/token evidence, fail-closed per-job exact-head worktrees for local review dispatch, authoritative post-agent delivery visibility (`delivery_status`), explicitly non-authoritative review visibility (`review_status` plus exact `head_sha`) graded `reported` for session journals and `observed` for sampled daemon-descendant liveness of dispatched review worktrees, durable bounded read-only-worktree diff capture for terminal background asks/reviews (`read_only_worktree_diff` plus explicit truncation/failure metadata), identity-safe recorded runtime PID liveness (`runtime_process_active`) and the doctor's hard ghost-job alarm, coordinator-only `task resume-work` with audited human-merge override friction, `workflow show`'s newest-100 default window and explicit truncation metadata, opt-in `[transcripts]` retention, and single/bulk `job transcript --export jsonl` trajectory export with atomic `0600` output and mandatory best-effort redaction.
- [Bridge](https://gitmoot.io/docs/reference/bridge): Authenticated localhost HTTP endpoint for external automation, including bounded string-map pipeline run payloads; token file auth and loopback-only default.
- [Runtime Adapters](https://gitmoot.io/docs/reference/runtime-adapters): Codex, Claude Code, Kimi Code, omp, shell, and future runtimes; lazy tri-state installed-CLI contract preflight (`supported`, blocking `unsupported`, fail-open recorded `unknown`) with executable-identity update detection and doctor visibility; warn-only adapter-derived permission-policy argv visibility (`applied`, `widened`, `not-applied`, `unresolved`) with a home-store fleet ratchet and nullable completion-effect capture attached to the same observation; the full omp contract (stateless fresh-session-per-job with the no-resume rationale, parse-derived success because exit 0 is not success, retry/terminal-state rules, summed per-message usage, explicit `--approval-mode=yolo` for every policy with read-only enforced Gitmoot-side, no cross-family mapping and its loud refusal, curated routing-plumbing environment); the config-driven metadata registry (`gitmoot runtime list`, `[runtimes.<name>]` overrides).
- [Runtime Ambient Credential Hygiene](https://gitmoot.io/docs/reference/credentials): Runtime credential custody — off-by-default child-environment curation with the exact allowlist and runtime exceptions, ambient GitHub credential denial or explicit inheritance, single-file Claude runtime auth, the loopback Claude model gateway (per-job placeholder tokens), and the named-key keychain: a metadata-only registry plus per-pipeline grants with own-key override, injected or configured `proxied` delivery (fixed-origin loopback leases, per-request grant re-check, revocation fail-closed), names-only audit, and the honest limits of each layer.
- [Execution Backend Selection](https://gitmoot.io/docs/reference/remote-exec): The `[remote_exec]` execution-backend seam — daemon jobs on `local` run in a job-scoped detached worktree, optional configured `local_uid`/`local_gid` drops agent-command privileges without a root fallback, `local_root` supports a traversable instance location, implement changes return transactionally with daemon-owned imports before result observation, cancel/destroy/reap own the instance lifecycle, a per-job `exec_backend` payload field overrides config, and unknown values fail loudly; distinct from Landlock local confinement.
- [Result Contract](https://gitmoot.io/docs/reference/result-contract): gitmoot_result shape, the delegations DAG (Orchestration), continuation, and termination bounds.
- [Event Stream](https://gitmoot.io/docs/reference/event-stream): The `[events]` webhook contract and opt-in organization event-rule Herdr wakes — addressed-by-default and observer rule scopes, `rule set-scope`, doctor coverage warnings for directed event kinds, job.finished/failed/blocked/needs_attention/deferred, candidate.*, durable `org.input_pending` re-nudges, direction-aware organization questions (ancestor escalation or descendant ask), escalation resolutions addressed back to their asker, coalesced addressed-note `org.reply` wakes, and delivery-only exact-targeted `org.fact` wakes backed by a SQL outbox, schema_version 1.
- [Codex And Claude Plugins](https://gitmoot.io/docs/plugins/codex-claude): Plugin discovery and runtime skill setup.
- [Troubleshooting](https://gitmoot.io/docs/operations/troubleshooting): Diagnose GitHub auth, bug reports, runtimes, agent templates, remotes, permissions, daemon lifecycle and stale advertised logs, stuck/deferred jobs, locks, delegation-worktree disk leaks and safe terminal-owner relief, transient merge deferrals while branch jobs are active, and the `gitmoot/merge-gate` status that marks a head the gate has not cleared.
- [Beta Smoke Tests](https://gitmoot.io/docs/operations/beta-smoke-tests): Deterministic smoke checklists for release validation.
- [Docs Deployment](https://gitmoot.io/docs/operations/deployment): How the docs site itself is built and published.
- [Release Notes](https://gitmoot.io/docs/release-notes/v0.9.1.3): Latest release (v0.9.1.3) — **the brain changelog**: an append-only `memory_events` journal records every fact mutation in-transaction (edits keep the previous content), browsable from the new `/brain` Graph|Changelog dashboard view (day-grouped live feed, before/after diffs, fact biographies, deep links) and from `gitmoot memory log` (+ idempotent `backfill` seeding history from existing tombstones). Plus keychain-secured pipeline credentials (registry, per-pipeline grants, proxied keys, env_file/env_keys injection), transcript retention with trajectory JSONL export, produce-stage `reads:` allowlists, and daemon reliability fixes (runtime-session lease heartbeats, checkout self-heal).
- [v0.8.7 Release Notes](https://gitmoot.io/docs/release-notes/v0.8.7): first-class Pipelines: a declared DAG of shell-runtime stages the daemon advances on demand or on a schedule, off by default (`gitmoot pipeline add|run|resume`), with an advancer cadence decoupled from repo-poll backoff and a committed-tip note on read-only top-level isolation (#681/#694/#700/#699). Reliability batch: reviews **re-sync** to a newer PR head instead of failing on a head-SHA mismatch (#691); GitHub API calls share a process-wide budget with adaptive secondary-rate-limit backoff (#692); blocked jobs record their `needs` as **resumable gates** — `gitmoot job gates`/`gates clear` satisfy them and auto-resume on the last clear (#693); full-chain E2Es cover the batch (#695).. Polish: product-style README (#688); dashboard moose logo + favicon (#689).
- [v0.8.6 Release Notes](https://gitmoot.io/docs/release-notes/v0.8.6): Codex token usage captured correctly for every session shape (#658/#661/#662/#664/#669); memory confirmed pool fills from ordinary jobs (#647); session jobs `job open/close/record` (#660/#676); daemon boot_id reboot recovery (#668); config-driven runtime metadata registry (#674/#679); dashboard Learning section (#672/#677/#680).
- [Raw SKILL.md](https://gitmoot.io/SKILL.md): Agent skill entrypoint.
- [Full LLM Context](https://gitmoot.io/llms-full.txt): Expanded Markdown context for agents.
- [GitHub Repository](https://github.com/gitmoot/gitmoot): Source code and releases.